📝 docs(vercel): record the new root-directory failure and the exact fix

[vtempest]

What

Docs-only. The grab-url Vercel project still has Root Directory docs, and now that #47 deleted that folder every deployment fails one step earlier — immediately after the clone:

Cloning github.com/OpenSourceAGI/GRAB-URL (Branch: master, Commit: 12dce81)
Cloning completed: 1.041s
The specified Root Directory "docs" does not exist. Please update your Project Settings.

instead of the old "/vercel/path0/docs/.next/routes-manifest.json" couldn't be found. Same cause, different message — .claude/architecture/documentation.md predicted exactly this.

Changes

• .claude/architecture/documentation.md — the docs/ section now describes the folder as deleted (commit c894e60) rather than on its way out; the Vercel section records both error messages and spells out the dashboard settings that fix it.
• .claude/architecture/conventions.md — the agent rules say don't recreate docs/, and the "red Vercel check is not your diff" rule names the current failure.
• CLAUDE.md — link description updated.

The actual fix (not in this diff)

Root Directory is a dashboard setting; no commit can change it. In Vercel → project grab-url → Settings → Build and Deployment:

1. Root Directory: docs → grab-help-docs
2. Leave Include source files outside of the Root Directory in the Build Step enabled
3. Clear the Install Command override (npm install --prefix=..); leave Build Command and Output Directory unset — grab-help-docs/vercel.json supplies all three

Testing

Documentation only — no code, build or test surface touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01V7vgUYbDNrEhFEUEQ2Tuci

---

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:08pm UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[vtempest]

The red test check on this PR is not this PR's — this diff touches only .claude/architecture/*.md and CLAUDE.md.

Tests is red on master itself: run 34608204942 on 18201a0, the base of this branch. Reproduced locally on that base — 11 failures, all in test/page-archive.test.ts, all of them the suite still testing the pre-98b613f (✨ feat(cli): route media-site URLs through yt-dlp) shape of packages/grab-url-cli/src/transfer/ytdlp-transfer.ts:

Failing test	Why
parseYtDlpSize() ×3	parseYtDlpSize is no longer exported
parseYtDlpEta() ×4	parseYtDlpEta is no longer exported
parseYtDlpProgress() ×2	now parses @GRAB@ progress-template lines, not the old human-readable [download] line; the old fixtures return null
buildYtDlpArgs() — base name	the option was renamed filename → output and is used verbatim, so the default %(title)s [%(id)s].%(ext)s comes back
misc — exit codes	exit 1 is now download failed — the media may be private, region-locked or removed

The module rewrite is intentional and documented in its JSDoc; the test file was simply not carried along. The two one-line ones:

-    it('uses the supplied base name but leaves the extension to yt-dlp', () => {
-        const args = buildYtDlpArgs('https://youtu.be/x', { filename: 'My Video' });
-        expect(args[args.indexOf('--output') + 1]).toBe('My Video.%(ext)s');
+    it('uses the supplied output template verbatim', () => {
+        const args = buildYtDlpArgs('https://youtu.be/x', { output: 'My Video.%(ext)s' });
+        expect(args[args.indexOf('--output') + 1]).toBe('My Video.%(ext)s');

-        expect(describeYtDlpExit(1)).toBe('download failed');
+        expect(describeYtDlpExit(1)).toBe('download failed — the media may be private, region-locked or removed');

The other nine need the progress-parsing tests rewritten against the sentinel-line API, which is a change of its own rather than a drive-by on a docs PR — happy to do it in a follow-up.

---

Generated by Claude Code