archilyzer

commit d2fe31854c5bee67b67ee947ed0791c5226c98f2
parent 9de04b774a4ff7a1485854e2a6da31989255284a
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date:   Wed, 30 Sep 2026 19:22:14 -0400

plans: slice DX, as shipped — the setup on the homepage's AI and MCP doc, the sites' Use with AI page removed and its links pointed there; FACTS; the changelogs

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Diffstat:
M
export/CHANGELOG.md
 | 
1
+
M
homepage/CHANGELOG.md
 | 
1
+
M
plans/FACTS.md
 | 
27
+++++++++++++++++++++++++++
M
plans/release-16.md
 | 
122
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

4 files changed, 151 insertions(+), 0 deletions(-)
diff --git a/export/CHANGELOG.md b/export/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Changelog
 
 ## [Unreleased]
+- **Use with AI goes to the Archilyzer site's AI and MCP doc; the page on each site is gone.** The header's, the slide-out menu's, the footer's and Ask AI's **Use with AI** keep their label and open https://archilyzer.pages.dev/docs/ai-and-mcp/ in the same tab, on every site and the hub, where one block says how to run Claude Code against any archive (the source, `pnpm install`, `claude mcp add archilyzer`, `/ask`). `/use-with-ai/` is no longer built. `corpus.json`'s `useWithAi` names the doc; `llms.txt`'s Ask AI section lists the site's `/ask/` chat and the doc; the sitemap drops `/use-with-ai`. Needs a rebuild and deploy of each site and the hub.
 - **A search with a layer that has nothing to read finishes.** A "Posts" layer under a tag chip, or a "Live chat" layer where no video in the selection has live chat, read "searched N/M…" for ever and never said "No matching videos."; it now finishes at once, having matched nothing. Needs a rebuild and deploy of each site and the hub.
 - **A search reads what the visitor ticks under "Search in": Transcripts, Posts and Live chat.** The Filters panel has a new row, **Search in**, beside Type. **Transcripts** and **Posts** are ticked by default and **Live chat** is not; Posts is offered only on a site that has posts, and Live chat only on a site with live chat. The row decides what a plain query reads: with Posts ticked, a plain query now finds posts as well as videos (before, a post was found only by a layer whose scope was "Posts"); with Live chat ticked, it finds live-chat messages too, shown in the same video's card beside the transcript hits, each marked "live chat"; with Transcripts unticked it reads no transcripts. A layer whose scope is picked by name in the query builder ("Live chat", "Posts", "Title / channel", …) reads what it names, whatever the row says. An empty query still lists every video the Type row keeps. With nothing ticked, Search and Apply filters are disabled and the row says "Search in: pick at least one". The Posts box moved here from the Type row, and unticking it no longer empties a layer whose scope is "Posts". Under a tag chip a plain query reads no posts, since a post carries no tags. The row is remembered, and saved with a profile; a shared link does not carry it, so it opens with the reader's own row. A live-chat hit now wears its "live chat" badge wherever it is shown, and the hint under the search bar says to tick Live chat under Search in. Posts unticked is now also remembered after a reload and restored with a profile, which it was not. Needs a rebuild and deploy of each site and the hub.
 
diff --git a/homepage/CHANGELOG.md b/homepage/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Homepage Changelog
 
 ## [Unreleased]
+- **The AI and MCP doc has a Ten-minute setup.** Right after the MCP server's introduction, one block runs Claude Code against a published archive, the Jeralyzer as the example: clone the source (or unpack the tarball on Downloads), `pnpm install`, `claude mcp add archilyzer`, start `claude` and try `/ask`; then what it needs, why the server must be registered as `archilyzer` (the shipped `/ask` and `/sweep` call `mcp__archilyzer__…`), the two optional editor lines for `fetch_clip`, `TRANSCRIPT_HUB_URL`, where the `mcp.json` form for other clients is, and WSL2 on Windows. "What it can do" is a heading of its own after it. Every archive's **Use with AI** link now lands on this page.
 - **`/source/` links the source's history.** A History block — how many commits (past 10,000, "the latest 10,000 of N"), the newest one (linking to its page), and links to the Log, the Refs and the Atom feed — shows when the build published the history pages (`/source/git/`, rendered by stagit); without them there is no History block. The history pages open on the homepage's ground (the reader's stored choice, else Dark; without JavaScript, the system's), start with one line back to `/source/`, and their Files page is an index into the raw tree. The e2e shows the page with and without a history from a fixture publish (`E2E_SOURCE_PUBLIC_DIR`, never read by a production build), and walks the real pages when the checkout has published them.
 - **The growth chart draws its smallest instances together as Other.** Two or more instances that each hold under 5% of the chart's total are one band, **Other**, on top of the stack, in a near-neutral grey of its own (`--chart-other`: 7.36:1 on the Light ground, 3.22:1 on the Dark one, and apart from every instance colour for colour-blind readers); an instance at exactly 5% keeps its band, and a single one under 5% is not grouped. The other instances keep their bands and their colours. The legend lists them and Other; the caption says what Other is and the chart's description names the instances in it; every month's hover title and the Numbers by year table still name every instance. At this release's numbers Hasanalyzer, Rekietalyzer and Jasolyzer are Other. The instance cards and `/stats` are unchanged. The e2e fixture's fifth site transcribes 4 a day rather than 5, so two of its six sites are grouped.
 - **An unlisted site is not on the homepage.** A site whose settings turn off **List on the Archilyzer homepage and hub** (`listed: false`) has no Official Instances card, chart series, `/stats` entry or recent item, is not in `channel-sites.json` or `stats/`, and the channels only it carries count in none of the numbers, the headline totals included. The summary's version is 6. The e2e fixture has a seventh, unlisted site that no page names.
diff --git a/plans/FACTS.md b/plans/FACTS.md
@@ -7939,3 +7939,30 @@ source mirror (homepage)". Anchors are at the branch.
   has no row.
 - **The export e2e fixture's posts have words of their own** (`kappa`, `sigma`, `omega` —
   `export/e2e/fixtures/data.ts`, `postsPage`), so a plain "alpha" or "gamma" in a spec reads no post.
+
+## 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
+  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).
+- **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,
+  label "Use with AI", same tab. `corpus.json`'s `useWithAi` keeps its key and names the doc (site
+  and hub); `llms.txt`'s "## Ask AI" is two lines, `[Ask AI](<base>/ask/)` and `[Use with AI](<doc>)`;
+  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
+  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.
+- **A multi-line JSX text that holds an HTML entity loses its leading space** under Next 16.2.3's
+  SWC: `<b>X</b> is the⏎project&apos;s` compiles to `"is the project's"` (without the entity, or on
+  one line, `" is the …"`). Put `{" "}` after the element. Measured 2026-09-30 by compiling every
+  `.tsx` with and without its entities (`next/dist/build/swc` `transform`): 22 texts in 19 files differ,
+  1 in `homepage/app/downloads/page.tsx` and 21 in `editor/app/**`; none in `export/app` or
+  `common/components`.
diff --git a/plans/release-16.md b/plans/release-16.md
@@ -384,3 +384,125 @@ fix; the drivers' fix alone passes all 15, the `runLeaf` short-circuit alone pas
 count is unchanged: one test extended); `pnpm --filter export exec next build` exit 0, 29 s;
 `search-in`, `query-tree` and `posts-search` at `500417f3`: **38 passed**, 0 failed, 1.9 min. The
 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`
+(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
+block on every site's page); on the amendment it was reset to `main` `2f09b065` (slice CK merged)
+and rebuilt, and of that first pass only the READMEs commit was kept (cherry-picked as `7921293f`).
+
+**What it does.**
+- **The homepage's AI and MCP doc has a "Ten-minute setup"** (`homepage/content/docs/ai-and-mcp.md`,
+  an `###` under "## The MCP server", right after its two opening paragraphs): one `sh` block —
+  `git clone https://archilyzer.pages.dev/source/archilyzer.git archilyzer   # or the tarball on
+  /downloads/`, `cd archilyzer && pnpm install`, `claude mcp add archilyzer --env
+  TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev -- pnpm -C "$PWD" --filter yt-dlp-transcript-mcp
+  exec tsx src/index.ts`, `claude  # then: /ask what has he said about …` — and seven notes: what you
+  need (Node.js 20.9 or newer, pnpm 9 or newer, Claude Code; no corpus, no yt-dlp, no GPU, nothing
+  hosted; the repo has no `engines` field, so the numbers are README's Requirements table), the
+  source ([git mirror](/source/), [tarball](/downloads/)), **register it as `archilyzer`** with the
+  one-sentence reason, the two optional editor lines for `fetch_clip`, `TRANSCRIPT_SITE_URL` /
+  `TRANSCRIPT_HUB_URL`, the `mcp.json` form for another client (in `mcp/README.md` on the raw
+  tree), and WSL2 on Windows (the README's "Claude Code on Windows", on the raw tree). "What it can
+  do:" became `### What it can do`, same words, so the list is not under the setup. Everything else
+  on the page is unchanged.
+- **The sites' `/use-with-ai` page is removed** (`export/app/use-with-ai/`, export and hub). Its
+  links keep the label **Use with AI** and go to `AI_DOC_URL` (`common/lib/project.ts`,
+  `${PROJECT_URL}/docs/ai-and-mcp/`), same tab, as plain anchors: the header's nav (its entry, and
+  `MobileMenu`'s, carry `external: true`), the footer's, and the one on Ask AI.
+- **What named the page names the doc:** `corpus.json`'s `useWithAi` (site and hub; the key stays),
+  `llms.txt`'s "## Ask AI" (two lines now: `[Ask AI](<base>/ask/)` for the chat and `[Use with
+  AI](<doc>)` for the MCP setup, site and hub), and the sitemap (`/use-with-ai` dropped).
+- **The READMEs are their own copies:** `mcp/README.md`'s "Add to Claude Code" and `mcp.json`
+  examples register `archilyzer` (were `rekietalyzer`) from `/ABS/PATH/TO/archilyzer`, the
+  directory the clone makes; its renaming paragraph stays and says why every example uses the name. `README.md` §1 registers with `pnpm -C "$PWD"`, "from the repo's
+  root" (was `/ABS/PATH/TO/this/repo`, against §4 and the Windows notes); §4's quickstart starts
+  from the source (`git clone …` or the tarball, then `cd archilyzer && pnpm install`). The
+  homepage's drift table (`homepage/content/README.md`) names README §1/§4 and mcp/README as copies
+  of the setup's commands, to change together; FACTS says the same.
+- **Specs.** `first-search` and `restore-no-refire` left the workspace through the header's Use with
+  AI, a client navigation in the same page life. No site link makes one to a page outside the
+  workspace now (the footer's Changelog is a plain `<a>`, a new page life), so they push
+  `/changelog/` through `window.next.router` (FACTS) and assert the Changelog heading and no query
+  builder before Back or the header's Search; their assertions are unchanged. `responsive` checks
+  `/changelog/` in place of `/use-with-ai/`, expected to fail (below).
+
+**Commits**
+
+| Commit | What |
+|---|---|
+| `7921293f` | `docs:` mcp/README registers `archilyzer` in both examples; README §1's `"$PWD"` |
+| `8bfecf14` | `common:` `AI_DOC_URL`; `corpus.json` `useWithAi`, `llms.txt`'s Ask AI, the sitemap |
+| `e5160555` | `export:` the page removed; the header's, the menu's, the footer's and Ask AI's links; `first-search`, `restore-no-refire`, `responsive`; `use-with-ai-link.spec.ts` (site and hub) |
+| `ab8d46a5` | `homepage:` the Ten-minute setup; the drift table; `docs.spec.ts` |
+| `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 |
+
+#### Gates (logs `$T/dx-*.log`)
+
+- **tsc** (all workspaces) clean, 70 s — after deleting the worktree's `export/.next/dev/types`,
+  left by the first pass's e2e dev server: its `validator.ts` imported the removed page (the build
+  regenerates `.next/types`; the dev copy waits for a dev server). Export and homepage alone again
+  after the spec fixes: clean.
+- **common:** 2,380/2,380, 129 s (the count unchanged: `corpus.test.ts`'s sitemap case takes
+  `/changelog` as its sample route). **`test:scripts`:** 194 passed, 2 skipped (the umtool post-build
+  check, whose worktree build predates its code; `LIVE`). **homepage unit:** 23/23.
+- **Builds:** `pnpm --filter export exec next build` exit 0, 33 s; the hub (`INSTANCE_MODE=hub`, the
+  same command) exit 0, 31 s. In each `out/`: no `use-with-ai/`; every "Use with AI" in the HTML
+  (the header's, the footer's, Ask AI's) has `href="https://archilyzer.pages.dev/docs/ai-and-mcp/"`;
+  no `href="/use-with-ai`. The homepage (`next build`, capped at 5 GB) exit 0, 22 s; the doc carries
+  the block. `eslint` on the touched export files: clean.
+- **e2e:** see the table below.
+- **Numbers tool** (`plans/tools/compose-fixture-one-youtube-channel`, composed into scratch): this
+  slice's differences are exactly `corpus.json`'s `useWithAi`, `llms.txt`'s two Ask AI lines and
+  `sitemap.xml`'s `/use-with-ai` entry. The committed fixture had already drifted from `main` (`spec`
+  3 → 4, four `_headers` entries, `index/sites/testsite/tag-counts.json`), so it was not updated.
+- **Privacy:** 0 matches of the operator's user name and 0 of the host name in every changed file,
+  but `plans/FACTS.md`'s user-name count of 3, which is `main`'s (0 in the lines this slice adds).
+
+  | Run | At | Specs | Result |
+  |---|---|---|---|
+  | 1 | `217d398f` | homepage `docs.spec.ts` | 4 passed, **1 failed** (`.doc-measure` matched three elements; fixed in `ae206b01`), 19 s |
+  | 2 | `217d398f` | export `use-with-ai-link`, `first-search`, `restore-no-refire`, `responsive`, `header` | 61 passed, **1 failed** (`/changelog/` overflows; marked in `ae206b01`), 4.9 min |
+  | 3 | `ae206b01` | homepage `docs.spec.ts` | **5 passed**, 0 failed, 19 s |
+  | 4 | `ae206b01` | the full export suite | **271 passed**, 0 failed, 15.1 min (`main`'s 267 + 4; `/changelog/`'s overflow case fails as marked, which the list prints as ✘ and counts as passed) |
+  | 5 | `ae206b01` | the hub suite | **39 passed**, 0 failed, 1.6 min (`main`'s 36 + 3) |
+
+#### Found and left
+
+- **`/changelog/` overflows a 390 px phone by about 600 px** (the new `responsive` case; it was not
+  checked before). Long inline `code` in released entries (`export/app/ask/{MessageBubble,…}.tsx/ts`,
+  a JSON literal) has no break opportunity. The case is `test.fail`, so a fix turns it red. Fixing it
+  is a change to the changelog's rendering, outside this ruling.
+- **A multi-line JSX text holding an HTML entity loses its leading space** under Next's SWC (FACTS):
+  22 texts in 19 files run a word into the element before it — 1 in `homepage/app/downloads/page.tsx`,
+  21 across `editor/app/**`; none in `export/app` or `common/components`. Found on the first pass's
+  page, which is gone. Not fixed.
+- **The compose fixture under `plans/tools/` is behind `main`** (above). Refreshing it is its own
+  commit.
+- `PUBLISH.md`'s registration (`-- pnpm -C "$PWD" archilyzer mcp`) and `AGENTS.md`'s (with the
+  editor lines) register `archilyzer` and were left as they are; `export/CHANGELOG.md`'s released
+  entry for the page is history.
+- A site deployed before its rebuild still serves `/use-with-ai/` and its old `corpus.json`; the
+  rebuild removes both together.
+
+#### Decisions the operator could overturn
+
+| What I did | The alternative |
+|---|---|
+| `AI_DOC_URL` in `common/lib/project.ts`, beside `INSTANCES_URL` | `${PROJECT_URL}/docs/ai-and-mcp/` written at each of the six places |
+| The header's and the menu's entries render a plain `<a>` (`external: true`) | `next/link` with the absolute URL, which also renders an `<a>` and does not client-navigate |
+| `corpus.json` keeps `useWithAi`, now the doc's URL | Drop the key (a contract change) |
+| `llms.txt`'s Ask AI section: the site's `/ask/` chat and the doc, two lines | One line, to the doc |
+| The sitemap drops `/use-with-ai` and adds nothing | Add `/ask/` |
+| `first-search` and `restore-no-refire` reach `/changelog/` through `window.next.router.push` | Click the footer's Changelog: a hard navigation, a new page life, which is not what those tests prove |
+| `responsive` checks `/changelog/` with `test.fail` | Drop the route; or fix the changelog's wrapping here |
+| "What it can do:" is `### What it can do`, same words | The setup at the end of "## The MCP server", after the list |
+| 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 |