# ARS v3.6.5.1 — SETUP.md Doc Correctness Fix — Implementation Brief

**Date**: 2026-04-27
**Target release**: v3.6.5.1 (patch, doc-only)
**Branch**: `hotfix/v3.6.5.1-setup-doc-correctness`
**Trigger**: GitHub issue #44 (philpav, 2026-04-27) + local Codex audit on `docs/SETUP.md`
**Author**: Cheng-I Wu

---

## Purpose of this document

This brief is the **non-negotiable constraint sheet** for the SETUP.md rewrite. It is given to Codex (or any drafter) so that the prose it produces respects ARS-specific invariants without re-deriving them. Without this brief, the drafter will likely:

- Misname skill folders or invent new directory structures
- Decide release semver / version bump on its own (not its call)
- Drift terminology away from existing repo conventions
- Skip the version sweep checklist
- Forget that this is a public repo with a Ruleset that blocks direct main commits

**This brief does not write the SETUP.md content itself.** It defines what content must achieve, what conventions it must follow, and what is out of bounds.

---

## §1 — Non-negotiable invariants

The drafter MUST follow these. Deviation requires a separate human decision, not a unilateral drafter call.

### 1.1 Skill folder structure

The repo has exactly **four skill folders** at the root, each with its own `SKILL.md`:

```
academic-research-skills/
├── deep-research/SKILL.md
├── academic-paper/SKILL.md
├── academic-paper-reviewer/SKILL.md
└── academic-pipeline/SKILL.md
```

There is **no root `SKILL.md`**. There is no plan to create one. Any install method that requires a single `SKILL.md` at the install path must install each skill folder separately, not the whole repo.

### 1.2 Skill discovery rule (Claude Code, Cowork, claude.ai upload)

The discovery convention all three platforms share is:

```
<install-root>/<skill-name>/SKILL.md
```

For Claude Code project skills: `<project>/.claude/skills/<skill-name>/SKILL.md`.
For Cowork: `~/.claude/skills/<skill-name>/SKILL.md`.
For claude.ai upload: each skill is uploaded as one zip, where the zip's top-level entry is `<skill-name>/SKILL.md` (not `<skill-name>/<skill-name>/SKILL.md`).

Any install instruction that produces `<install-root>/academic-research-skills/<skill-name>/SKILL.md` (extra nesting level) is broken — Cowork / Claude Code / claude.ai will not discover the skill.

### 1.3 Method 4 (claude.ai) is two distinct sub-methods

**Sub-method 4a**: Real Skill upload via Settings → Capabilities → Skills, one zip per skill. This is the path that gives skill auto-loading and trigger phrase routing. Currently blocked by the 200-char description cap (fixed in v3.6.5.2, NOT v3.6.5.1).

**Sub-method 4b**: Project + GitHub integration loads files into Project knowledge (static retrieval context). This is NOT a Skill install — Claude can read the files but does not execute them as agentic skills.

The SETUP.md must distinguish these two clearly. 4a is the "real" install; 4b is fallback knowledge mode. Do not conflate.

### 1.4 Public repo, Ruleset-protected main

`Imbad0202/academic-research-skills` is a public repo with branch protection that blocks direct commits to main (GH013). All changes must go via PR. The drafter does not commit directly. The drafter does not invent its own branch name; the branch is `hotfix/v3.6.5.1-setup-doc-correctness` (already created by human).

### 1.5 Authoritative sources for terminology

When in doubt about Cowork / claude.ai UI terminology, prefer (in order):

1. **Anthropic official docs** (highest authority — these are the upstream truth):
   - Claude Code Skills paths and discovery: https://code.claude.com/docs/en/skills
   - Custom Skills packaging (incl. ≤200-char description cap): https://claude.com/docs/skills/how-to
   - Cowork getting started + requirements: https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork
   - Cowork Projects (left nav, "Use an existing folder"): https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork
   - Cowork Skills via plugins (`/` and `+` UI surface): https://support.claude.com/en/articles/13837440-use-plugins-in-claude-cowork
   - Projects (claude.ai static knowledge): https://support.claude.com/en/articles/9517075-what-are-projects
   - GitHub integration (auth, private-repo App, Team/Enterprise enablement): https://support.claude.com/en/articles/10167454-using-the-github-integration
   - Connectors setup (Team/Enterprise owner enablement): https://support.claude.com/en/articles/10168395-set-up-claude-integrations
   - Project file limits (per-file 30 MB, count unlimited): https://support.claude.com/en/articles/8241126-upload-files-to-claude

2. **Issue #44 reply (already vetted UI wording, inlined below for self-contained reference):**

   > Cowork install — symlink approach the user already validated:
   > ```bash
   > git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills
   > mkdir -p ~/.claude/skills
   > cd ~/.claude/skills
   > ln -s ~/academic-research-skills/deep-research deep-research
   > ln -s ~/academic-research-skills/academic-paper academic-paper
   > ln -s ~/academic-research-skills/academic-paper-reviewer academic-paper-reviewer
   > ln -s ~/academic-research-skills/academic-pipeline academic-pipeline
   > ```
   > "Restart Cowork and the four skills should register."
   >
   > claude.ai distinction (verbatim phrasing the user used):
   > "the GitHub integration loads files into Project knowledge, not Skills. Real Skill upload needs each skill zipped separately via Settings → Capabilities → Skills, and descriptions in this repo currently exceed the 200-char limit so they'd reject."

3. **Existing `docs/SETUP.md` text** — only for parts the audit (§2 below) did not flag as drifted. Do not lift wording from sections F1-F7 covered by this brief.

Never invent a UI term. Never paraphrase a UI label as a "more readable" alternative — the literal label is what the user clicks. When Anthropic doc and issue #44 reply disagree on a UI label, Anthropic doc wins (it is the upstream truth as of the doc's last-updated date).

### 1.6 Out of bounds (do not touch)

The drafter must NOT modify these as part of v3.6.5.1:

- Any `SKILL.md` (description, frontmatter, body) — those are v3.6.5.2 scope
- Any agent file under `*/agents/`
- Any schema under `shared/`
- Any script under `scripts/`
- Any test under `tests/`
- The branch protection / Ruleset config
- The CHANGELOG section ordering or version numbering convention (just append a new v3.6.5.1 entry above v3.6.5)

The drafter MAY modify (within v3.6.5.1 scope) — this list is the **complete allowed-edit set**:

- `docs/SETUP.md` (primary work)
- `docs/SETUP.zh-TW.md` if it exists (mirror EN changes)
- `README.md` and `README.zh-TW.md` install method sections (sweep, only if they mention Cowork or claude.ai install)
- `.claude/CLAUDE.md` install-related sections (sweep, only if drifted from v3.6.5.1)
- `QUICKSTART.md` install-related sections (sweep, only if drifted)
- `CHANGELOG.md` (add v3.6.5.1 entry)

**Sweep vs edit boundary** (resolves apparent conflict with §4): the §4 sweep grep MAY scan a broader path (e.g. all of `docs/`) to find install-method mentions, but the drafter MAY edit only the files in the allowed-edit set above. Hits outside the allowed-edit set are **report-only**: list them in the validation report for human review, do not auto-edit. Touching files outside the allowed-edit set requires explicit human approval (out of v3.6.5.1 scope).

The drafter does NOT decide:

- Whether v3.6.5.1 ships as a tag, a release, or just a merge — that is the user's call
- Whether the issue #44 follow-up comment goes out at v3.6.5.1 or v3.6.5.2 — already decided (deferred to v3.6.5.2 per ROADMAP)
- Whether SKILL.md description trim is in this patch — already decided NO (v3.6.5.2)

---

## §2 — Findings to fix in v3.6.5.1

Source: local Codex audit on `docs/SETUP.md` 2026-04-27.

### F1 (P0) — `docs/SETUP.md:213-229` Method 3 wrong path

**Problem**: Current Option A says clone repo to `.claude/skills/academic-research-skills/`. This produces:

```
.claude/skills/academic-research-skills/deep-research/SKILL.md   ← buried, not discovered
```

instead of the required:

```
.claude/skills/deep-research/SKILL.md   ← Cowork finds this
```

Same problem in Option B if it follows the same pattern.

**Authoritative source**: Claude Code Skills paths and discovery convention — https://code.claude.com/docs/en/skills

**Fix**: Rewrite Option A and Option B to install each of the four skill folders separately into `.claude/skills/`. Two acceptable approaches:

- **Option A — symlink (fastest, single-machine)**: `git clone` repo to a stable path (e.g. `~/academic-research-skills`), then `ln -s <repo>/<skill-name> ~/.claude/skills/<skill-name>` for each of the four skills. Must include a caveat: if the user syncs `~/.claude/skills` across machines via cloud folders, prefer `cp -R` because absolute-path symlinks break on a fresh checkout (this is a real ARS lesson from `feedback_relative_symlinks_in_repos.md`).
- **Option B — copy (cross-machine safe, no auto-update)**: `git clone` repo, then `cp -R <repo>/<skill-name> ~/.claude/skills/<skill-name>` for each of the four skills. Note that updates require re-running cp.

The four skill folder names are exact: `deep-research`, `academic-paper`, `academic-paper-reviewer`, `academic-pipeline`. Use bash code blocks with explicit per-skill commands.

**Hard rule on consolidation** (resolves apparent conflict with §8 drafter judgement zone): the drafter MAY consolidate Option A and Option B into a single section if it improves readability, BUT every final command must name all four skill folders explicitly. No `for skill in ...` loop, no parameterised one-liner, no "repeat for each skill" instruction without showing each command. Reason: readers copy-paste in a hurry and skip iteration syntax; explicit four-line blocks have ~zero misuse rate.

### F2 (P0) — `docs/SETUP.md:237` Method 4 conceptually wrong

**Problem**: Current text says "use these skills on claude.ai via the Project feature with GitHub integration". This frames GitHub integration as a Skill install path. It is not — GitHub integration loads files into Project knowledge (static retrieval context), not the Skills system. Skill auto-loading and trigger phrase routing do not happen via this method.

**Authoritative sources**:
- Projects (claude.ai static knowledge): https://support.claude.com/en/articles/9517075-what-are-projects
- GitHub integration: https://support.claude.com/en/articles/10167454-using-the-github-integration
- Custom Skills packaging (zip per skill, ≤200-char description): https://claude.com/docs/skills/how-to

**Fix**: Restructure Method 4 into two clearly labelled sub-methods. Use neutral framing — neither is "recommended" right now (4a is blocked on v3.6.5.2; 4b is documented-but-limited):

- **Method 4a — Custom Skill upload (claude.ai's standard Skill install path)**: Settings → Capabilities → Skills, upload one zip per skill (the zip's top-level entry must be `<skill-name>/SKILL.md`, matching the `name` field in the skill's frontmatter). **State the current blocker explicitly**: the four skill `description` fields in this repo currently exceed the 200-char cap and would be rejected by the upload UI; the description trim ships in patch v3.6.5.2 immediately after this v3.6.5.1 doc patch. The path is documented here so the install instructions are correct in advance; until v3.6.5.2 ships, prefer Methods 1, 2, or 3.
- **Method 4b — Project + GitHub integration (fallback knowledge mode, not a Skill install)**: GitHub integration loads files into Project knowledge for retrieval. **Explicitly state**: "this is NOT a Skill install. Skill auto-loading does not happen. Trigger phrases do not route. Claude can read the repo content but does not execute the skills as agentic workflows. Useful when you want claude.ai to have access to the repo content for reading/citation but you do not need agentic skill execution."

### F3 (P1) — `docs/SETUP.md:233` Method 3 prereqs missing

**Problem**: Current line is one sentence: "Requirements: Claude Desktop (latest version) with Cowork enabled; paid plan."

**Authoritative source**: Cowork getting started + requirements — https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork

**Fix**: Expand into a `**Prerequisites**` subsection covering:

- Claude Desktop latest version (macOS or Windows; link to Anthropic Desktop download page)
- Active internet connection (Cowork tasks call Anthropic API)
- Desktop app must remain open during Cowork task execution (Cowork runs inside the Desktop process)
- Folder/file permissions: Cowork needs read/write access to the project working folder
- Org-level controls: on Team or Enterprise plans, your org admin may have disabled Skills, plugins, connectors, or egress; if symlinks/skills do not register after restart, ask your admin
- Paid plan: Pro, Max, Team, or Enterprise (cite the Cowork article above for current plan availability — do not paraphrase the plan list, link to it because Anthropic adjusts plan tiers)

### F4 (P1) — `docs/SETUP.md:241` Method 4 prereqs missing

**Problem**: Current line is one bullet: "1. Sign in to claude.ai (requires a paid plan)".

**Authoritative sources**:
- GitHub integration (auth, App authorization, Team/Enterprise enablement): https://support.claude.com/en/articles/10167454-using-the-github-integration
- Connectors setup: https://support.claude.com/en/articles/10168395-set-up-claude-integrations
- Custom Skills packaging (4a): https://claude.com/docs/skills/how-to

**Fix**: Expand into a `**Prerequisites**` subsection (apply to both 4a and 4b where relevant) covering:

- Paid plan (link to Anthropic plan page; do not paraphrase tier list)
- **For Method 4a (Skill upload)**: no GitHub auth needed; zip each skill folder locally so the zip's top-level entry is `<skill-name>/SKILL.md`; upload via Settings → Capabilities → Skills. Note that zip structure errors and the 200-char description cap will surface as upload-time errors per the Custom Skills doc.
- **For Method 4b (GitHub integration)**: GitHub authentication via the Anthropic connector (see Connectors setup link); private repos require the Anthropic GitHub App authorized on the repo or org; Team/Enterprise plans require owner-level connector enablement before users can add GitHub-sourced files.

### F5 (P2) — `docs/SETUP.md:217-218` Cowork UI terminology drift

**Problem**: Current text says: "click **Cowork** tab (top bar)" and refers to a "working directory". Both wrong against current Cowork UI.

**Authoritative sources** (use the literal labels from these pages — do not paraphrase):
- Cowork access (mode selector wording): https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork
- Cowork Projects (left nav, "Use an existing folder", Cowork Project): https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork

**Fix**: Use current Cowork UI terms:

- "mode selector (Chat / Cowork)" — the toggle between Claude's two modes
- After switching to Cowork, the relevant view is **Tasks**
- Left navigation panel offers "Use an existing folder" to create a Cowork Project pointing at a local folder
- The folder is referred to as a **Cowork Project**, not "working directory"

Walk the reader through each click using the literal current UI labels from the linked Anthropic pages.

### F6 (P2) — `docs/SETUP.md:231` Trigger phrase oversimplified

**Problem**: Current text says skills are invoked "via trigger phrases". True but incomplete — Cowork now also surfaces installed plugin Skills via the `/` command palette and the `+` (add capability) visual UI. The audit also notes that "trigger phrase" is itself a slight overstatement: Claude uses the skill description to decide relevance, not literal trigger-phrase matching.

**Authoritative sources**:
- Skills invocation (Claude uses description for relevance, not literal trigger matching): https://code.claude.com/docs/en/skills
- Cowork Skills via plugins (`/` and `+` UI): https://support.claude.com/en/articles/13837440-use-plugins-in-claude-cowork

**Fix**: List three discovery surfaces and correct the trigger-phrase framing:

- Description-based relevance (the primary mechanism, per Claude Code Skills doc): Claude reads each skill's `description` and routes the user request to whichever skill it judges most relevant. The example phrases in the SETUP table are illustrative, not literal triggers.
- `/` command palette in Cowork: type `/` and the four skills appear as completions for explicit invocation.
- `+` capability picker in Cowork: visual UI to add a skill to the current Task.

Reader should know that explicit `/` and `+` UI exist as a fallback when description-based routing does not pick the desired skill, and that paraphrased intent ("help me draft a paper") works equally well as the example phrases.

### F7 (P2) — `docs/SETUP.md:243-255` Method 4 directory table omits `scripts/` + capacity outdated

**Problem**: Current Method 4 directory table omits `scripts/`, but adapter and validator workflows live there and break without it. The audit also notes the section's capacity rationale references a 200-file cap that conflicts with current Anthropic Project limits (the audit team did not actually find the 200-file claim on line 235-264 — it may already have been removed in an earlier doc rev — but the surrounding capacity guidance is shaky and needs a refresh against current limits).

**Authoritative source**: Project file limits (per-file 30 MB; file count unlimited subject to total content/context limits) — https://support.claude.com/en/articles/8241126-upload-files-to-claude

**Fix**:

- Add a `scripts/` row to the directory table with rationale "literature_corpus[] adapters (folder_scan, zotero, obsidian) + schema validators; required for Material Passport corpus mode and CI-style validation."
- Rewrite the capacity section: state current Anthropic Project limits per the linked page (file count is not artificially capped at 200; per-file 30 MB; total subject to context-window limits at runtime). If the existing text still contains the 200-file claim, remove it; if it does not, just add the current-limits reference for clarity.
- Keep the practical guidance "Method 4b is for content reading, not active Skill execution; if you need agentic skill execution, prefer Methods 1-3 or 4a (after v3.6.5.2)."

---

## §3 — Banner removal

The hotfix branch already has banners on Method 3 and Method 4 (commit `d176578`). After the rewrite addresses F1-F7, the banners must come out. Their purpose was harm reduction during the patch interval; once the instructions are correct, the banners are noise.

**Drafter responsibility**: prepare banner removal as part of the SETUP.md rewrite diff. The drafter does not commit (per §1.4 — public repo, drafter never commits directly). The human maintainer reviews the diff and decides whether banner removal goes in the same commit as the F1-F7 rewrite (atomic) or as a separate commit immediately after (cleaner history). Recommended commit message if separate: "remove banners superseded by v3.6.5.1 SETUP rewrite".

---

## §4 — Sweep checklist

After SETUP.md is fixed, grep the rest of the repo for install-method mentions and align:

```bash
grep -rn -E "Cowork|claude\.ai|claude\.com/product/cowork|GitHub integration|\.claude/skills" \
  README.md README.zh-TW.md QUICKSTART.md .claude/CLAUDE.md docs/ \
  --exclude-dir=design
```

Any hit inside the §1.6 allowed-edit set that contradicts the v3.6.5.1 SETUP.md must be aligned. Hits outside the allowed-edit set are **report-only** per §1.6: list them in the validation report for human review, do not auto-edit. Files known to potentially need touch (verify; update only if drifted):

- `README.md` — Quick Start / Installation section
- `README.zh-TW.md` — same as English
- `QUICKSTART.md` — if it exists and mentions Cowork or claude.ai
- `.claude/CLAUDE.md` — Skills Overview table is unlikely to need changes (no install instructions there), but check
- `docs/SETUP.zh-TW.md` — mirror EN changes if zh-TW exists (may or may not — check first)

Files NOT to touch in v3.6.5.1: anything under `*/agents/`, `shared/`, `scripts/`, `tests/`, individual `SKILL.md` files.

---

## §5 — Validation gate

Validation has two tiers: **required (filesystem path-shape)** and **optional (live discovery)**. Required must pass before opening PR; optional is documented when environment supports it, otherwise reported as "not validated in this run" without blocking ship.

### 5.0 Environment protection (mandatory before any validation)

The drafter / validator MUST NOT pollute the developer's real `~/.claude/skills` while validating instructions. Two acceptable approaches:

- **Disposable HOME**: `tmpdir=$(mktemp -d)` then run validation steps with `HOME=$tmpdir`. Filesystem checks resolve against `$tmpdir/.claude/skills/`. Cleanup is `rm -rf $tmpdir` when done.
- **Backup + restore**: `mv ~/.claude/skills ~/.claude/skills.backup-pre-v3.6.5.1-validation`, run validation, then `rm -rf ~/.claude/skills && mv ~/.claude/skills.backup-pre-v3.6.5.1-validation ~/.claude/skills` after. Riskier — if the validation step fails partway, the backup might not get restored. Disposable HOME is preferred.

Document which approach was used in the validation report.

### 5.1 Required: filesystem path-shape validation

These steps verify that the corrected SETUP.md instructions produce the right paths on disk. They do NOT require Claude Desktop, Claude Code session, Cowork, or claude.ai access.

For each install method below, run the exact commands from the v3.6.5.1 SETUP.md draft (no edits, no shortcuts) inside the protected environment from §5.0:

1. **Method 1 (project skills)**: confirm `<project>/.claude/skills/deep-research/SKILL.md` exists at the expected path and is the file from the repo (not a placeholder). Repeat for the other three skills.
2. **Method 3 Option A (symlink)**: confirm `~/.claude/skills/deep-research/SKILL.md` resolves (test with `test -f`, not `ls -L`, to follow symlinks). Confirm `readlink` shows the absolute path back to the cloned repo. Repeat for all four skills.
3. **Method 3 Option B (copy)**: confirm `~/.claude/skills/deep-research/SKILL.md` exists, is a regular file (not symlink), and content matches `<repo>/deep-research/SKILL.md` (e.g. `diff` returns 0). Repeat for all four skills.

All three must pass. If any path-shape check fails, the SETUP.md instructions are still wrong and the rewrite is not done.

### 5.2 Optional: live discovery validation

These steps verify that platforms actually discover the installed skills. Run them only when the corresponding platform is available; otherwise mark as "not validated in this run" in the validation report.

4. **Method 1 live**: open Claude Code in the project directory, start a session, confirm the four skills appear in the available-skills list. (Available if Claude Code is installed locally.)
5. **Method 3 live (Cowork)**: with the protected `$HOME` from §5.0 set as the active HOME for the Claude Desktop session, restart Claude Desktop, switch to Cowork mode, confirm the four skills appear under the `+` capability picker. (Available only if Claude Desktop is installed and Cowork is enabled on the account.)
6. **Method 4a live**: zip one skill folder per the SETUP.md instructions, attempt upload via Settings → Capabilities → Skills. Expected outcome **before v3.6.5.2 ships**: rejection with a description-too-long error, which validates that the documented upload path is the right one and that v3.6.5.2 description trim is the correct unblocker.
7. **Method 4b live**: connect a claude.ai Project to the GitHub repo per Method 4b instructions, confirm the file tree appears in Project knowledge and is selectable for Claude to read.

### 5.3 Validation report format

The validation report is a Markdown block included in the PR description (or attached as a file under `examples/v3.6.5.1-validation/` if it is large). Required content:

- Which §5.0 environment-protection approach was used
- For each of steps 1-3: PASS / FAIL with the exact command output that proves it
- For each of steps 4-7: PASS / FAIL / NOT VALIDATED (reason: e.g. "no Claude Desktop on validation machine"). Marking "NOT VALIDATED" is acceptable for steps 4-7; it is not acceptable for steps 1-3.

Open the PR only after steps 1-3 pass. Steps 4-7 results inform reviewers but do not block.

---

## §6 — Codex review iteration

After the SETUP.md draft is complete (and sweep is done):

1. Bundle the draft + this brief + the original audit findings into a single file.
2. Run `codex exec --sandbox read-only` with a verification task: "Apply the v3.6.5.1 brief constraints; flag any deviation. Output severity-tagged findings."
3. Iterate fixes; re-run Codex.

**Ship gate** (refined from `feedback_codex_iterative_spec_review_to_zero.md` discipline for the doc-patch context):

- **Zero P1 and zero P2 findings**: required. Every P1 and P2 finding must be fixed before ship. No "reject with rationale" path for P1/P2 — they are blockers by definition. If a Codex P1 or P2 is technically wrong (e.g. Codex misread the brief), the response is to clarify the brief or argue the finding back, not to declare it rejected and ship.
- **P3 findings**: either fixed, OR accepted with one-line rationale in the PR description (e.g. "P3 wording preference declined: deviates from the user's vetted issue #44 phrasing"). P3 wording or stylistic findings should not block ship indefinitely; rejection-with-rationale is the P3-only escape hatch.
- The "zero findings" phrasing was developed for high-blast-radius schema/contract spec (e.g. v3.6.2 sprint contract) where any drift could cascade through validators and runtime. SETUP.md is moderate blast radius (broken instructions harm new users but do not corrupt data); P3 acceptance is the correct trade-off here. P1/P2 are non-negotiable in both contexts.

Reviewing prose against a brief is what Codex is good at; reviewing prose against vague stylistic preferences is not. Keep the brief as the contract. When Codex raises a P3 that the brief does not actually constrain, accept-with-rationale rather than re-engineering the brief mid-iteration.

---

## §7 — PR body template

When opening the PR, the body should:

- Reference issue #44 by URL
- Summarise F1-F7 fixes (one line each)
- Note that v3.6.5.2 (description trim) is the planned follow-up patch and that issue #44 close happens at v3.6.5.2 ship, not at this PR merge
- Link to ROADMAP commit `eb240b4` for the patch sequencing decision
- List validation steps performed (per §5)

Do NOT reference internal terminology (e.g. "blast radius", "Codex second-opinion"). PR is public-facing.

---

## §8 — What this brief deliberately does not specify

These are intentionally left to the drafter's judgement:

- Exact section ordering inside SETUP.md (the drafter may reorganise for readability as long as F1-F7 are addressed)
- Inline code formatting style (bash vs shell prompt syntax) as long as consistent within the doc
- Word choice within the constraints of §1.5 authoritative sources
- Whether to consolidate Method 3 Options A and B into a single set of commands with toggles, or keep them as separate options (drafter's call based on readability)

These are explicitly delegated; no follow-up question needed.
