[stephane-segning]

1. Summary

Adds a documentation site for meta-whatsapp-rs, built with VitePress and the vaam-apps house theme @vaam-apps/vitepress-md3 (seed #128c7e). It covers the existing docs/ pages and adds a home page and a getting-started page. A new docs.yml workflow builds the site on every PR and deploys it to GitHub Pages from main at https://vaam-apps.github.io/meta-whatsapp-rs/.

2. Intent

The ~18 pages in docs/ (guides, architecture, the service design, coverage/parity/categories, roadmap) are only readable on GitHub today. A site gives them navigation, search and a reading order without moving or rewriting them. Every existing file stays at its path, so links into them keep working.

3. Scope

In

• docs/package.json, docs/pnpm-lock.yaml, docs/pnpm-workspace.yaml: docs/ is a standalone pnpm project. The workspace file holds only the pnpm 12 release-age exclusion for theme 1.0.0, which was published today. It says when to delete it (after 2026-10-22).
• docs/.vitepress/config.ts, docs/.vitepress/theme/index.ts. The sidebar runs in reader order: Start here (Introduction, Getting started) → Guides (index, then the guides in the order guides/README.md gives) → Architecture and design → What is implemented (coverage, parity, categories) → Plan (roadmap, OPEN_QUESTIONS on GitHub) → Development (dev environment, CONTRIBUTING and CHANGELOG on GitHub). The config also has local search, edit links and an MIT footer.
• docs/index.md (home) and docs/getting-started.md (dependency, feature flags, crates, API reference, examples, the service, agent skills). Both are taken only from README.md and the crates' Cargo.toml. There are no docs.rs links: every crate is publish = false and nothing is on crates.io. The page says so and gives cargo doc -p meta-whatsapp-rs --all-features --open, as the README does.
• docs/public/logo.svg: an M3 cookie shape in the seed colour with a white chat bubble.
• .github/workflows/docs.yml: a new file with SHA-pinned actions. It builds on every PR, then on main it uploads the Pages artifact and runs deploy-pages.
• .gitignore: adds docs/node_modules, docs/.vitepress/dist and docs/.vitepress/cache.

Out

• No existing .md file is edited. Many of them link to files outside docs/ with relative paths (../../crates/…, ../../OPEN_QUESTIONS.md), and docs_tables.rs checks those paths. Rather than rewrite them, the config has a small markdown-it rule that turns those links into https://github.com/vaam-apps/meta-whatsapp-rs/{blob,tree}/main/… URLs at build time. Heading anchors use GitHub's slug rule, so the pages' existing #anchors (#1-on-metas-side and the like) work on the site too.
• No Rust code, Cargo manifests, ci.yml or skills are touched.
• Docs/skills parity (AGENTS.md): rustdoc n/a (no public API change); docs/ gets new pages only, no existing page changed; skills/ n/a (no API change).

4. Verification

• cd docs && pnpm install --frozen-lockfile && pnpm build: build complete (pnpm 12.14.0, Node 22.22). ignoreDeadLinks: false, so any dead internal link would fail this build.
• Checked every internal href and #anchor in the built HTML with a script: 0 missing pages, 0 missing anchors. The 40 links rewritten to GitHub all point to files that exist.
• cargo test -p meta-whatsapp-rs --all-features --test docs_tables with this branch's tree: 11/11 pass. This covers the new pages under the link/anchor and citation checks.
• markdownlint-cli2 with the org default config (markdownlint/style/prettier, MD060 aligned) on docs/index.md and docs/getting-started.md: 0 issues.
• zizmor --offline .github/workflows/docs.yml: no findings. yamllint -d relaxed on the workflow and the pnpm YAML files: line-length warnings only, no errors.
• just ci was not run in full (it needs Postgres/Redis and the full toolchain run). This PR's CI runs it.
• The Docs workflow's deploy job can only run after merge, on main.

5. Screenshots / Evidence

Reviewed locally from vitepress preview: the home page (light, full page and 390 px mobile), getting-started, the webhooks guide in dark mode, and parity. The hero, feature cards, sidebar, outline and tables all render. The PR build of the Docs workflow is the reproducible check.

6. Risk Assessment

• Low for the library: nothing outside docs/, .gitignore and one new workflow changes.
• Watch out for local just ci after a docs install. docs_tables.rs's walk() goes into every directory under docs/ except target. After pnpm install in docs/, it walks docs/node_modules and picks up third-party READMEs. links_and_anchors_in_the_docs_resolve and cited_items_decisions_and_questions_exist then fail locally. I reproduced this: 2 failures with docs/node_modules present, 11/11 pass without it. CI is not affected, because ci.yml never installs the docs packages. I left the test alone because this PR stays out of code. The one-line fix is to skip node_modules beside target in walk() (crates/meta-whatsapp-rs/tests/docs_tables.rs). Until then, delete docs/node_modules before running just ci.
• docs/pnpm-workspace.yaml is temporary. Delete it after 2026-10-22.

7. AI Usage Declaration

• AI generated the code/config in this PR (Claude Code)
• AI wrote the new pages (from README.md and the crates' Cargo metadata only)
• AI ran the verification listed above
• Human verification: content reviewed for accuracy
• Human verification: site checked in the PR build / after deploy

8. Reviewer Focus

• The link-rewrite rule and GitHub slugify in docs/.vitepress/config.ts.
• Whether docs/getting-started.md says anything the README does not.
• The node_modules / docs_tables.rs interaction in section 6.

After merge, a repo admin must: go to Settings → Pages → Build and deployment → Source and set GitHub Actions. The site will then be at https://vaam-apps.github.io/meta-whatsapp-rs/. If you use a custom domain, set it there too; the workflow passes Pages' base path to the build, so no code change is needed.

---

Generated by Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[lightbridge-assistant]

🅵 Fast automated pass — SAST + a quick, diff-scoped look (no repo-wide retrieval). For a deeper, repo-aware review, mention @lightbridge-assistant on this PR.

Reviewed all changed files: docs.yml (pins, least-privilege permissions, no secrets on fork PRs, artifact/deploy split all correct), .gitignore, theme/index.ts, config.ts (outsideDocs normalization + slugify), logo.svg (no script), package.json, pnpm-workspace.yaml (minimumReleaseAgeExclude is a real pnpm 10.16+ setting, valid name@version), and both markdown pages — none has a code defect. SAST was clean. The single P2 is docs/.vitepress/config.ts:8: the DOCS_BASE || "/meta-whatsapp-rs/" fallback mis-handles the empty base_path that actions/configure-pages returns for a custom-domain/root deployment, so the advertised "domain change needs no code change" would build the site against the wrong base. NOT reviewed in depth: docs/pnpm-lock.yaml (generated lockfile).

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).

[stephane-segning]

just ci failed at just deny, but this PR didn't cause it. New RustSec advisories hit rustls, rustls-webpki, webpki-roots and webpki-root-certs, and yoke-derive 0.8.3 was yanked. Those versions come from Cargo.lock on main, which this PR doesn't touch.

The fix is in its own PR, #34, which changes only the two lockfiles. I've merged that branch into this one (ae9a3d5) so just deny passes here as well. The merge changes nothing once #34 is on main.

---

Generated by Claude Code