Scribe Guide — comment banners and Markdown sidecars

Plain English first. Sharp edges after.

1. What this is / is not

Scribe writes locked comment banners on your scripts so you remember what they do. It can also write a Markdown sidecar next to the file. Mechanical always works. Brain = None is first-class. Optional polish (Unity AI, Grok / Claude / Codex CLIs, or extras) only warms wording — never invents APIs, never requires a pasted key, never needs Node in the Editor.

It is not Charter (game plans). It is not Atlas (code map). It is not Folio (markdown viewer). Those are sibling kits. Scribe may soft-friend Folio and Atlas when they are installed; it never hard-depends on them.

2. Open it

Everything hangs under:

ArTchie / Scribe / …

Job	Click
Open the Scribe window (comment path)	ArTchie / Scribe / Comment Selection
Open the Scribe window (doc path)	ArTchie / Scribe / Document Selection
Document every supported script under a folder	ArTchie / Scribe / Document Folder
Rewrite Markdown that is older than its script	ArTchie / Scribe / Rebuild Stale Docs

Comment Selection and Document Selection open the Scribe window. Select script(s) in the Project window, then use the window buttons (Comment selection / Document selection).

Document Folder and Rebuild Stale Docs open the same window and start the job on the current Project selection (folder asset, or files/folders with stale sidecars).

Supported extensions: .cs .js .ts .tsx .jsx .mjs .cjs .bedder.

3. First five minutes

1. In the Project window, select one .cs (or JS/TS) script you own.
2. Click ArTchie / Scribe / Comment Selection. The Scribe window opens.
3. Leave Polish brain on None (mechanical only). Click Comment selection.
4. Open the script. You should see a file banner (title bar, HOW IT WORKS, analogy, WHAT IT EXPORTS, optional USED BY) plus a short banner above each public function. If it already had banners, status says so — nothing is rewritten.
5. Click Document selection. A FileStem.md appears beside the script (or under a Docs/ subfolder if that toggle is on). If Folio is installed, the Console may hint Open with Folio / Open.

That is enough. Optional polish comes later — never required for a good first pass.

4. The meat

Banner shape (locked)

File banners are ~80 columns wide, boxed with // ─── rule lines. Shape:

// ── Title ─────────────────────────────────────────────────
//
// <short module blurb>
//
// HOW IT WORKS:
// <intro>
//   1. …
//   2. …
//
// Think of it like …
//
// WHAT IT EXPORTS:
//   Name(…)  — short gloss
//
// USED BY: …          (only when mechanical / Atlas found callers)
// ───────────────────────────────────────────────────────────

Per-function banners:

// ───────────────────────────────────────────────────────────
// Name(params)
//
// <gloss>
// Example: …
//   param — gloss
// ───────────────────────────────────────────────────────────

Empty files and thin Unity-lifecycle scripts still get a real numbered HOW IT WORKS list from what is in the file (title, types, serialized fields, or the object's lifetime) — not a dummy “keep the public surface documented” step. WHAT IT EXPORTS may say (no public functions found); types already parsed are named in a short line. Untitled / Script files say they have little public surface instead of pretending they “handle the untitled/script work.”

Already had banners → Comment Selection leaves the file alone (success, no rewrite).

Document Selection / Folder

Markdown sidecar sections:

• # Title
• ## Summary (2–4 sentences)
• ## Details (public types, methods, important fields; Properties and Events when present — empty property/event blocks are omitted)
• ## How to use (numbered steps)
• ## Used by / depends on (unknown if empty)
• ## Source + Generated by Scribe (mechanical)

Default path: same folder as the script, FileStem.md. Toggle in the window: Write Markdown into a Docs/ subfolder.

Document Folder walks recursively under the selected folder asset(s) (or a mix of files + folders in the window). Skips Library/, Packages/, node_modules.

Batches of 2+ show a cancelable progress bar (title Scribe, info n / N · filename). Cancel stops remaining files and remaining polish. Status: Cancelled after n of N. The bar is always cleared when the job ends. A single file can skip the bar.

Rebuild Stale Docs

A sidecar is stale when it exists and the script’s mtime is newer than the .md. Missing sidecars are not stale.

Menu uses the current selection (files or folders — same walk as Document Folder). Window shows N stale sidecar(s) and Rebuild stale docs. Rebuild re-runs mechanical TryDocument (optional polish of Summary / How to use, same rules).

Brain picker — None first

Order in the window:

1. None (mechanical only) — always works
2. Unity AI / Assistant (optional)
3. Grok CLI · Claude Code CLI · Codex CLI (first-class; logged-in binary, no API key)
4. Extras: Local Ollama · Anthropic key · OpenAI-compat / xAI key (never required)

Settings live in EditorPrefs (Scribe.*), not in the package. Nothing requires a pasted key to comment or document.

What polish may rewrite

Surface	May change	Must not change
Comment banners	HOW IT WORKS wording + numbered steps; the single Think of it like line	WHAT IT EXPORTS, USED BY, signatures, code, banner rules
Markdown docs	Summary; How to use	Details (no invented APIs); Used by / depends on; Source footer

If the brain drifts, returns empty text, or tries to touch locked bits, mechanical text stays. Use Polish wording in the window when you want a second pass on already-commented files.

CLI detect

In the Scribe window: Detect paths fills Grok / Claude / Codex from common home bin folders and PATH (plus Extra PATH). Status stays grok: Found|Missing · …. If any say Missing, that is optional polish only — install that CLI, Detect again, sign in. Comment and Document still work with Brain = None. Node is not required in the Editor.

Missing optional brain (HelpBox)

• Brain = None: plain never-blocks line — Comment and Document still run.
• Unity AI absent: Warning HelpBox — not in this project (com.unity.ai.assistant); optional polish unavailable; mechanical path stays; no key needed.
• CLI not found: Warning HelpBox — click Detect paths (or type the binary path), then sign in; Comment and Document still run with Brain = None — no pasted key.
• Extras (Ollama / Anthropic / OpenAI-compat): optional — never required; same Brain = None reassurance. Prefer Detect CLIs over pasting a key.

Soft friends — Folio and Atlas

• Folio (com.artchie.folio): after a successful Document write, Scribe may log Open with Folio / Open. Folio is never required; reflection probes Folio.FolioWindow.
• Atlas (com.artchie.atlas): Document Selection / Folder / Rebuild append inbound callers to Used by via reflection (ScribeAtlasBridge). No asmdef reference. If Atlas is missing, the index cache is missing, or reflection fails: Used by stays mechanical (unknown if empty). The bridge never throws. Depends on is never replaced by Atlas. CLI document stays mechanical-only (no Atlas).

5. Common stuck

1. Menus say Scribe / … without ArTchie/ — stale README. Trust Unity: ArTchie / Scribe / ….
2. Comment Selection did nothing visible — it opens the window. Select a script, then click Comment selection. Already-bannered files report success without rewriting.
3. It wants a key / brain Warning — Comment and Document are never blocked. Set Polish brain = None, or Detect paths + sign in for optional polish. Prefer logged-in CLIs over pasting a key.
4. Document Folder freezes / no progress — batches of 2+ should show a cancelable bar. If you cancel, expect Cancelled after n of N. and a cleared bar.
5. Rebuild Stale finds nothing — missing sidecars are not stale. Document once first, then edit the script, then rebuild.
6. Used by always unknown — alone script with no sibling callers, or Atlas not installed / index not built. Mechanical path is fine; Atlas only enriches when present.
7. Polish left mechanical text / Polish wording disabled — brain not ready (Unity AI missing, CLI Missing → Detect paths + sign in), or the reply drifted off the locked shape. Fix the brain, or stay on None — mechanical banners/docs already shipped.

6. For pros

CLI (node scribe.js)

node scribe.js FILE
node scribe.js document FILE
node scribe.js document-folder DIR
node scribe.js stale DIR
node scribe.js document --stale DIR

• Default / bare FILE = comment (mechanical banners).
• document / document-folder = Markdown sidecars. Mechanical only. No polish. No Atlas.
• document-folder prints n/N file on stderr. Ctrl+C / SIGINT → Scribe: cancelled after n of N. (non-zero exit).
• stale lists stale source paths (one per line), exit 1 if any. document --stale rebuilds only those.
• Walks skip node_modules, Library/, Packages/.

C# Editor path (ScribeMechanical) stays in sync with scribe.js banner rules — Unity does not shell out to Node.

EditorPrefs brains

Prefix Scribe.:

Key area	Purpose
Brain	enum int — None=0 … OpenAi=7
Cli.Grok / Cli.Claude / Cli.Codex / Cli.PathExtra	detected or typed binary paths
Docs.Subfolder	bool — Markdown under Docs/ vs beside script
Ollama.* / Anthropic.Key / OpenAI.*	extras only

Never ship keys inside the package.

Polish merge contract

• Comments: extract HOW IT WORKS + Think of it like; splice; reject if WHAT IT EXPORTS or code changed.
• Docs: extract Summary + How to use; splice; reject if locked sections changed.
• Details must not invent APIs that were not in the parse.

Soft reflection (no hard deps)

• Folio: type probe for opener hint after write.
• Atlas: AtlasStore / AtlasIndexer.EnsureLoaded (cache must already exist — no rebuild) / AtlasQuery.Trace inbound depth 1–2.

Canonical package

com.artchie.scribe · Unity 2021.3+ · base artchie-RECONCILED-20260822-2107. Deeper topic notes: package Documentation/DocumentSelection.md, DocumentFolder.md, DocFreshness.md, UsedBy.md.

7. Related kits

Kit	When you want it
Suite Map	Which ArTchie pile does what · Guides/Guide-Suite-Map.md
Folio	Read the Markdown sidecar in the Editor (Scribe may hint Open)
Atlas	Index / who-calls — soft-enriches Scribe Used by
Charter	Game plan + Genre Blueprints (can call Scribe soft)
Bedder	In-player IDE / scripts — optional Scribe polish after CsToBedder
Anvil / Rivet	Project health · daily Editor chores
ArTchie AI	Companion chat — uses Atlas when both present; never require a pasted key

Do not invent a third docs kit. Mechanical first. Brain = None is enough.