commit 7986763d7ea10a0a29e1ca2ca1a76027d6ef257e
parent 842336856642f5a53584610c270d3c556af11b94
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Wed, 30 Sep 2026 19:42:12 -0400
plans: slice DX after the review — FACTS says which README carries what (L1), the record's base (L4), the slices table's DX row as amended; the review's findings; STATE's two follow-ups
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Diffstat:
3 files changed, 46 insertions(+), 8 deletions(-)
diff --git a/plans/FACTS.md b/plans/FACTS.md
@@ -7942,12 +7942,16 @@ source mirror (homepage)". Anchors are at the branch.
## Use with AI is the homepage's AI and MCP doc (verified 2026-09-30, branch `r16/research-setup`)
-- **The research-only setup lives on the homepage doc; `README.md` §1/§4 and `mcp/README.md` are
+- **The research-only setup lives on the homepage doc; `README.md` §1/§4 and `mcp/README.md` carry
copies to change with it.** `homepage/content/docs/ai-and-mcp.md` "Ten-minute setup": clone (or
the tarball) → `cd archilyzer && pnpm install` → `claude mcp add archilyzer --env
- TRANSCRIPT_SITE_URL=…` → `claude`, `/ask`. README §1 and §4 and mcp/README's "Add to Claude Code"
- and `mcp.json` examples say the same steps and register `archilyzer`; nothing shares text between
- `homepage/content` and the READMEs (`homepage/content/README.md`'s drift table names them).
+ TRANSCRIPT_SITE_URL=…` → `claude`, `/ask`. **README §4's quickstart carries that whole sequence,
+ in the same order** (its command adds the two optional editor lines). **README §1 and
+ mcp/README's "Add to Claude Code" and `mcp.json` examples share only the registration**, `claude
+ mcp add archilyzer … -- pnpm -C <checkout> --filter yt-dlp-transcript-mcp exec tsx src/index.ts`:
+ README §1 with `"$PWD"` from the repo's root, mcp/README with the placeholder
+ `/ABS/PATH/TO/archilyzer`. Nothing shares text between `homepage/content` and the READMEs
+ (`homepage/content/README.md`'s drift table names them).
- **A site has no `/use-with-ai` page** (export and hub). `AI_DOC_URL` (`common/lib/project.ts`,
`${PROJECT_URL}/docs/ai-and-mcp/`) is the target of the header's nav entry (a plain `<a>`: the
header's and `MobileMenu`'s links take `external: true`), the footer's link and Ask AI's link,
@@ -7956,7 +7960,9 @@ source mirror (homepage)". Anchors are at the branch.
the sitemap's routes are `/`, `/changelog` (+ `/downloads`, `/duplicates` when built).
- **A route outside the workspace, in the same page life, is reached in a spec through
`window.next.router.push(…)`.** Next 16.2.3 sets `window.next.router` "for debugging"
- (`next/dist/client/components/app-router-instance.js:388`), in development and production. Since
+ (`next/dist/client/components/app-router-instance.js:388`), in development and production. It is
+ undocumented (not in `node_modules/next/dist/docs/`): check it first on a Next upgrade; if it is
+ gone, the specs fail with a TypeError rather than pass. Since
the header's Use with AI left the site, no site link makes a client navigation to a page outside
the workspace (the footer's are plain `<a>`, a new page life; Downloads and Duplicates show only
when built), so `first-search` and `restore-no-refire` push `/changelog/` that way.
diff --git a/plans/STATE.md b/plans/STATE.md
@@ -25,6 +25,11 @@ reviewed SHIP). The operator's runbook is `~/reports/release-15/RUNBOOK.html`.
`export`'s `WorkspaceView` `splitOn` has a one-paint flash from a localStorage restore;
"Load more results" never resumes a leaf that settled at its cap (`runQueryTree`'s `setHitLimit`
reaches running leaves only; on `main` too — release 16 CK re-review R-I1; wants a spec).
+ - `/changelog/` overflows a 390 px phone: long inline code in a released entry
+ (`export/CHANGELOG.md:103`, the 133-character `export/app/ask/{useAskChat,…}` list) cannot wrap. Wrap `<code>` in the changelog renderer, then drop
+ the `test.fail` in `export/e2e/responsive.spec.ts` (release 16 DX).
+ - The JSX entity/whitespace hazard sweep: 22 texts in 19 files run a word into the element before
+ them (FACTS, "Use with AI is the homepage's AI and MCP doc"; release 16 DX).
**Now (2026-09-28, night): the stats cache key fix — built, reviewed (SHIP AFTER FIXES, then SHIP
on re-review; every touch-up done), not merged.** The branch is `fix/stats-cache-key`, and [`stats-cache-key.md`](stats-cache-key.md)
diff --git a/plans/release-16.md b/plans/release-16.md
@@ -22,7 +22,7 @@ slice's prompt carries its ruling, and this record carries what was built. Rules
| Slice | Branch | What | Owns |
|---|---|---|---|
| CK | `r16/search-in` | A "Search in" row — Transcripts, Posts, Live chat — on the export and hub search, Transcripts and Posts on by default | `common/components/{FiltersPanel,SearchSessionContext,SearchResults,SearchBar,exportFilterStorage}.tsx/.ts`, `common/lib/searchQuery.ts` and `common/lib/search/*` as its prompt names, `export/e2e/search-in.spec.ts` (new) and the specs its prompt names, `export/e2e/helpers.ts`; records: `plans/FACTS.md` |
-| DX | `r16/research-setup` | The research-only setup (source → `pnpm install` → `claude mcp add archilyzer` → `/ask`) on the homepage's AI doc, every site's Use-with-AI page and the two READMEs | `homepage/content/docs/ai-and-mcp.md`, `export/app/use-with-ai/page.tsx`, `mcp/README.md`, `README.md` §1/§4 (wording only), `homepage/e2e/docs*.spec.ts` and `export/e2e/use-with-ai*.spec.ts` as its prompt names |
+| DX | `r16/research-setup` | The research-only setup (source → `pnpm install` → `claude mcp add archilyzer` → `/ask`) in one place, the homepage's AI and MCP doc; the sites' and the hub's Use-with-AI page removed and its links pointed at the doc; `README.md` §1/§4 and `mcp/README.md` their own copies (as amended) | `homepage/content/docs/ai-and-mcp.md`, `export/app/use-with-ai/` (removed), the Use with AI links (`export/app/components/{Header,MobileMenu,Footer}.tsx`, `export/app/(workspace)/ask/page.tsx`), `common/lib/{project,corpus}.ts` + `common/bin/compose-site.ts` (what named the page), `mcp/README.md`, `README.md` §1/§4 (wording only), `homepage/e2e/docs.spec.ts`, `export/e2e{,-hub}/use-with-ai-link.spec.ts` and the specs that visited the page |
## Slice CK — the ruling (2026-09-30)
@@ -387,7 +387,7 @@ full export suite and the hub suite were not re-run, as the parent directed.
### Slice DX, as shipped — the research-only setup, told where a visitor reads (2026-09-30)
-Branch `r16/research-setup` off `main` `2b767bc9`, worktree `~/Projects/homepage-social-visible`
+Branch `r16/research-setup` off `main` `2f09b065` (first cut at `2b767bc9`, reset on the amendment), worktree `~/Projects/homepage-social-visible`
(block #3: editor 3301, test 3311, export 3310), one Opus implementer. Scratch files `dx-*` in the
job's `tmp`. Built to the ruling as amended the same evening ("Slice DX — the ruling" above): the
branch was first built to the ruling as first written (a shared `common/lib/researchSetup.ts` and the
@@ -441,7 +441,10 @@ and rebuilt, and of that first pass only the READMEs commit was kept (cherry-pic
| `217d398f` | `docs:` README §4's quickstart starts from the source |
| `ae206b01` | `export(e2e)`, `homepage(e2e)`: `/changelog/`'s overflow marked `test.fail`; `docs.spec`'s locator |
| `6027b0dc` | `docs:` mcp/README's two examples name the checkout `/ABS/PATH/TO/archilyzer` |
-| this commit | `plans:` this section; FACTS; the export and homepage changelogs |
+| `20605b5f` | `plans:` this section; FACTS; the export and homepage changelogs |
+| `1fcb224d` | `common:` review L3 — `corpus.test` pins `useWithAi` (site and hub) and llms.txt's two Ask AI lines |
+| `cadc595e` | `homepage:` review L2 — the doc names `fetch_clip` as the one exception to "it only reads" |
+| this commit | `plans:` review L1 (FACTS), L4 and the slices table's DX row; the review's findings; STATE's two follow-ups |
#### Gates (logs `$T/dx-*.log`)
@@ -506,3 +509,27 @@ and rebuilt, and of that first pass only the READMEs commit was kept (cherry-pic
| The doc's notes include where the `mcp.json` form is (the removed page carried it) | Leave it out |
| README §4's quickstart gains the clone step, with the tarball's host in its comment | Leave §4 starting at `pnpm install` |
| The doc's `/ask what has he said about …` (README §4's words) | "they", for any archive |
+
+#### Review
+
+**Verdict: SHIP AFTER FIXES** (`dx-review.md` in the job's scratch): four lows, no High or Medium.
+
+| Finding | Where |
+|---|---|
+| L1: FACTS said README §1, §4 and mcp/README "say the same steps" | This commit: README §4 carries the doc's whole sequence in the same order; README §1 and mcp/README share only the registration command (§1 with `"$PWD"`, mcp/README with `/ABS/PATH/TO/archilyzer`) |
+| L2: the doc brought in `fetch_clip` beside "it only reads already-published static JSON" | `cadc595e`: "The one exception is `fetch_clip`, which asks a local Archilyzer editor for a clip's media: the editor writes it, and the server itself never writes." |
+| L3: nothing pinned the composer changes | `1fcb224d`: `useWithAi === AI_DOC_URL` for site and hub; the two "## Ask AI" lines of each llms.txt; no `use-with-ai` in either |
+| L4: the record's base | This commit: off `main` `2f09b065`, first cut at `2b767bc9` |
+| I1: `window.next.router` is undocumented | This commit: FACTS says so, and to check it first on a Next upgrade |
+| I2: `test.fail` is satisfied by any failure, not only the overflow | Left as ruled; STATE's follow-up drops the line once the changelog wraps |
+| I3: the slices table's DX row described the first ruling | This commit: the row states the amended scope |
+| I4: the primary's `export/.next/{,dev/}types` still name the removed page | The parent's, before the post-merge tsc |
+| I5–I8 | No action here (deploy order: the homepage with or before the sites and hub; README's Windows blocks' `<your-remote>` a follow-up) |
+
+**Follow-ups in `STATE.md`:** `/changelog/`'s overflow (wrap `<code>` in the changelog renderer, then
+drop the `test.fail`); the JSX entity/whitespace sweep (22 texts in 19 files, FACTS).
+
+**Gates after the review** (logs `$T/dx-regate.log`, `$T/dx-e2e4.log`): tsc (all workspaces) clean,
+125 s; common **2,381/2,381** (+1), 166 s; mcp **271/271**, 59 s; homepage `docs.spec.ts` **5
+passed**, 19 s; export `use-with-ai-link.spec.ts` **4 passed**, 12 s; the hub's **3 passed**, 10 s.
+The full suites were not re-run, as the parent directed.
