fix(workspace): disambiguate docs package and document local setup

[kim-benedict]

What

Give the docs app a unique, private package name so pnpm --filter comark selects only the parser. Add a contributor guide covering source stubs, examples, plugins, checks and signed commits, and link it from the README. Update the bundle snapshot for the README addition.

Why

The docs app shares the parser's name, so a focused parser test passes and then fails when pnpm also runs it in docs. #147 reports missing setup guidance; the guide explains the current stub-based workflow and when compiler watchers are useful.

Related #147. The separate Nuxt playground request remains outside this PR.

Validation

Checked with Node 24.21.0 and pnpm 12.5.1:

• pnpm install --frozen-lockfile passes without lockfile changes.
• The same pnpm --filter comark exec vitest run test/parse/sub-sup.test.ts command now runs only in packages/comark and passes all 3 tests.
• pnpm verify passes: lint, 2,123 package tests and typecheck.
• pnpm prepack and the updated bundle snapshot check pass; pnpm stub restores source exports afterward.
• The default Vue example loads in Chromium without page errors or a compiler watcher, and requests the local core/renderer source modules. Nuxt preparation for the docs app also passes.

The first verification run hit a 10ms timeout in an unchanged Markdown fixture; both subsequent full runs passed.

Summary by CodeRabbit

• Documentation
  • Expanded contributor guidance with setup, example and documentation workflows, testing and build checks, plugin development, formatting, and pull-request preparation.
  • Added a link to contributor guidance in the package README.
  • Updated project instructions to clarify local setup, example workflows, and stub behavior.
• Chores
  • Renamed the private documentation-site package.
  • Updated the expected published package size to 376 kB.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: b522c94a-b070-4f58-b3fe-58d037b608a7

📥 Commits

Reviewing files that changed from the base of the PR and between 70d929c and c9a7aad.

📒 Files selected for processing (5)

• AGENTS.md
• CONTRIBUTING.md
• docs/package.json
• packages/comark/README.md
• test/bundle.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The changes add contributor setup and workflow guidance, link to it from repository documentation and the comark README, rename the documentation-site package, and update the expected published comark package size.

Changes

Repository guidance and maintenance

Layer / File(s)	Summary
Contributor setup and workflow CONTRIBUTING.md, AGENTS.md, packages/comark/README.md	The new guide covers local setup, examples, package responsibilities, plugins, verification, and pull requests. AGENTS.md updates its example workflow guidance, and the comark README links to the guide.
Package metadata and bundle expectation docs/package.json, test/bundle.test.ts	The docs package name changes to comark-docs-site. The expected published comark size changes to 376k; the expected file count remains 160.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to c9a7a

The contributor guidance and package rename show no established blocker to merging after normal checks.

Architecture Summary

Architecture risk: 🔵 Low · up to c9a7a

The change affects 5 systems.

Changed systems: AGENTS.md, CONTRIBUTING.md, docs, packages/comark, test

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — AGENTS.md (service) was modified; 1 changed file maps to changed impact.
• observed — CONTRIBUTING.md (service) was modified; 1 changed file maps to changed impact.
• observed — docs (service) was modified; 1 changed file maps to changed impact.
• observed — packages/comark (library) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in AGENTS.md: The playground/ directory entry was removed from the monorepo structure.
• observed — Modified behavior in AGENTS.md: The Common Tasks section now links to CONTRIBUTING.md for setup and example-app workflow, and explains that installation runs pnpm stub, which points examples at package sources, and that running it after a build restores those source exports.
• observed — Modified behavior in AGENTS.md: The pnpm dev:playground script entry was removed; the example-running command is now documented as pnpm dev:<name> with supported example names.
• observed — Modified behavior in CONTRIBUTING.md: Adds contribution guidance and local setup steps, including Node.js and pnpm requirements, generated source stubs, and installation commands.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the package-name change and local setup documentation, which are central changes in the pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[vercel]

@kim-benedict is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.

[coldtea-pr-lens]

Note

This drawing shows c9a7aad, and the branch has new commits since. Tick Redraw to draw the latest one

• Redraw

✅ Clean pass · drawing c9a7aad looks sound on architecture, data flow and security

Architecture

Data flow

No data-flow sequence changed in this PR.

View

• Architecture lens
• Data flow lens
• Expand every detail

Tip

The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change

🪧 More tips

• Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists
• Untick Architecture lens or Data flow lens under View to hide a diagram, or tick Expand every detail to open every section. The comment redraws in a few seconds
• Click the link under each diagram to open it on a canvas you can zoom, pan and step through
• Open a diagram on the canvas, then press W or click play to walk through the change one step at a time
• The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time
• Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture and data flow row. Drawing still runs as before
• Set github.draw: on-demand in .github/pr-lens.yml and PR Lens stops drawing pull requests on its own. Comment @pr-lens draw on a pull request when you want that one drawn
• Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works
• Push a commit and the drawing stays, with a note that it is out of date. Tick Redraw in the note to draw the new head
• Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion

---

Thanks for using PR Lens! It's built by Coldtea, free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Bluesky
• Mastodon
• Reddit
• LinkedIn