📝 docs(claude): tidy the four loose ends left by the #47/#48/#49 merges

[vtempest]

Follow-up to #49, which merged at 13:59 while this reconciliation was still being written — so these four fixes missed it by about a minute. #49 is merged and can't carry them, hence a fresh PR.

Four files, +22/−9, documentation only.

What's wrong on master right now

1. .gitignore carries both PRs' .claude blocks, stacked

#48 and #49 each added one and the merge kept both:

.claude/*
# Architecture notes for Claude agents — checked in on purpose (see CLAUDE.md)
!.claude/architecture
…
.claude/*
# Agent docs for Claude Code — checked in on purpose (see CLAUDE.md)
!.claude/architecture
!.claude/settings.json
.claude/settings.local.json
CLAUDE.local.md

Collapsed to the second, which is a superset — it keeps the un-ignore that makes .claude/settings.json trackable and the local-only excludes.

2. CLAUDE.md ground rule 4 says #47 "removes" docs/

#47 merged; the folder is gone. Changed to past tense.

3. grab-help-docs/CLAUDE.md still describes docs/ as a live landing page

The root docs/ directory — a small static landing page for grab.js.org

It no longer exists. Rewritten around what still matters: it's deleted, don't recreate it, and the Vercel project's Root Directory still points at the missing folder — with a pointer to documentation.md, which has the dashboard fix.

4. Nothing referenced the per-package CLAUDE.md files or monorepo.md

#49 added nine per-package files and monorepo.md, but the root CLAUDE.md — which came from #48 — has no pointer to either, so an agent reading it never learns they exist. Added a row and a line to the Detailed-notes section.

Also

packages/grab-api/CLAUDE.md now carries the zero-runtime-dependencies claim that #48 raised to a repo-wide ground rule. It's the single most important constraint on that package and its own file didn't state it.

Verification

• All four confirmed live on master before fixing, and confirmed fixed here.
• .claude/settings.json still tracked after the .gitignore collapse; all 6 .claude files still tracked.
• Every .claude/architecture/*.md link in CLAUDE.md resolves.
• No code touched — test/ and packages/grab-url-cli/src/ are untouched, so the 11 pre-existing failures in test/page-archive.test.ts (red on master since ✨ feat(cli): archive a page into a folder with --page #45) are unchanged, as is the Vercel check, whose Root Directory is a dashboard setting no commit can fix. Both were diagnosed in the 📝 docs(claude): add per-package CLAUDE.md files and monorepo.md #49 comments.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EoGK1G8bnF6riGQekWLtYr

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
grab-url	Error		Sep 11, 2026 2:02pm UTC

[vtempest]

Both red checks are inherited from master; neither is fixable here

Vercel — now failing earlier, and the error finally names the cause outright

Deleting docs/ in #47 changed the failure mode, exactly as that PR predicted. The deployment no longer gets far enough to produce build logs at all:

errorCode:    NOW_SANDBOX_WORKER_ROOTDIR_NOT_EXIST
errorMessage: The specified Root Directory "docs" does not exist.
              Please update your Project Settings.
errorStep:    build-container-init

Previously it reached the build and died on a missing docs/.next/routes-manifest.json; now it fails at container init, before anything runs. Same single cause, stated in Vercel's own words.

The fix is two settings changes in the dashboard, and no commit can do it:

1. Root Directory → grab-help-docs
2. Clear the npm install --prefix=.. Install Command override, and leave Build Command unset

grab-help-docs/vercel.json then supplies framework, install and build commands. Every deployment of this project has failed for days, production included.

test — the 11 pre-existing failures

Unchanged: test/page-archive.test.ts has failed 11 of its 59 since #45 added it, and master's own Tests run is red. This PR touches four .md files and .gitignore — no code, so nothing here moves that number. Fully diagnosed in #49's comments; reconciling that file with ytdlp-transfer.ts is work for #45's author.

I'm not re-running either check: both are deterministic, and a re-run would only reproduce them.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!