docs: add root visuals/ output convention for generated visual aids

[AdamRoch]

Intent

The developer (acting as an autonomous crewmate agent for the firstmate orchestration repo) was tasked with adding a captain-approved convention to firstmate's AGENTS.md governing where generated visual aids and artifacts (Lavish boards, HTML explainers, dataviz pages) are written: to a top-level visuals/ directory at a repository root rather than buried in internal agent directories like data/ or .lavish/, with project-specific visuals going to that project's own root visuals/ and firstmate's fleet/operational visuals going to the firstmate home's root visuals/. Requirements included following the firstmate-coding-guidelines skill (one-owner rule, concise placement, repo style of one sentence per line, no em dashes), placing the rule once in AGENTS.md (section 9 suggested) without duplicating it into skills, and adding visuals/ to the repo's .gitignore matching the existing data/, state/, config/ entries. Scope was docs and config only: no script or skill output-path changes, with conflicting hardcoded paths (e.g. .lavish/ defaults) only noted as follow-on work in the PR description. The change had to ship via the no-mistakes validation pipeline as a PR held for the captain's merge, with ask-user findings escalated rather than self-resolved and no use of --yes. During the run, the captain additionally approved fixing a review finding by listing the new home-root visuals/ entry in both home-layout owner documents (AGENTS.md section 2's layout block and docs/configuration.md's operational-home-layout section), and after a push failure due to the AdamRoch account lacking write access, approved a fork-based PR from AdamRoch:fm/firstmate-visuals-convention into kunchenguid:main, with the PR URL to be reported once CI is green and no merging performed.

What Changed

• AGENTS.md section 9 now states the convention for generated visual aids (Lavish boards, HTML explainers, dataviz pages): write them to a root-level visuals/ directory instead of internal agent directories like data/ or .lavish/ — project visuals go to that project's own root visuals/ via its normal delivery path, and firstmate's fleet/operational visuals go to this home's root visuals/.
• Both home-layout owner documents list the new directory: AGENTS.md section 2's layout block and the operational-home-layout section of docs/configuration.md, each pointing to section 9 as the rule's owner.
• .gitignore adds a visuals/ entry alongside the existing data/, state/, and config/ entries, keeping home-root visuals private and untracked.

Deferred as follow-on work: existing hardcoded output paths (e.g. the .lavish/ defaults referenced in .agents/skills/bearings/SKILL.md) are intentionally unchanged; those pointers stay accurate until the tooling defaults migrate to visuals/.

Risk Assessment

✅ Low: Docs-and-gitignore-only change that matches the approved scope, respects the one-owner rule with correct section references, and touches no executable code.

Testing

Exercised the docs/config change end-to-end: demonstrated the new .gitignore entry actually hides a generated home-root visual from git (check-ignore transcript saved), verified the convention is stated once in AGENTS.md section 9 with both home-layout owner docs referencing it, confirmed repo style compliance (one sentence per line, no em dashes) and docs-only scope, and captured a rendered screenshot of all changed sections; no relevant automated tests exist to run and none assert the real .gitignore, and all checks passed.

• Evidence: Rendered changed doc sections (new lines highlighted) (local file: /var/folders/fg/kdtsctls07xdptm648h0n5bc0000gn/T/no-mistakes-evidence/01KY73PPMHWB5PZBS7HNBYZ2WX/visuals-convention-docs.png)

Evidence: gitignore behavior transcript (home-root visual invisible to git)

$ mkdir -p visuals && touch visuals/fleet-status-board.html $ git check-ignore -v visuals/fleet-status-board.html .gitignore:4:visuals/ visuals/fleet-status-board.html $ git status --porcelain # (empty = generated visual is invisible to git) $ git status --short | wc -l 0

$ mkdir -p visuals && touch visuals/fleet-status-board.html
$ git check-ignore -v visuals/fleet-status-board.html
.gitignore:4:visuals/	visuals/fleet-status-board.html
$ git status --porcelain   # (empty = generated visual is invisible to git)
$ git status --short | wc -l
       0

Evidence: HTML source of rendered evidence page

<!doctype html><meta charset="utf-8"><title>visuals/ convention — changed doc sections</title>
<style>
body{font-family:-apple-system,sans-serif;max-width:1100px;margin:24px auto;padding:0 16px;background:#0d1117;color:#e6edf3}
h1{font-size:20px} h2{font-size:14px;color:#8b949e;font-weight:600;margin:28px 0 8px}
.code{background:#161b22;border:1px solid #30363d;border-radius:8px;padding:8px 0;font:12px/1.7 ui-monospace,Menlo,monospace}
.ln{display:flex;white-space:pre-wrap;padding:0 12px}
.ln .n{color:#484f58;width:38px;flex:none;text-align:right;margin-right:14px;user-select:none}
.ln.new{background:rgba(46,160,67,.18)} .ln.new .c{color:#7ee787}
.ln .c{min-width:0;word-break:break-word}
</style>
<h1>firstmate: <code>visuals/</code> output convention — rendered changed sections (new lines in green)</h1>
<section><h2>AGENTS.md — section 2 &quot;Layout and state&quot; (home layout block)</h2><div class="code"><div class="ln "><span class="n">105</span><span class="c">  .afk               durable away-mode flag; present = sub-supervisor may inject escalations (set by /afk, cleared on user return)</span></div><div class="ln "><span class="n">106</span><span class="c">  .watch.lock .wake-queue.lock watcher singleton and queue serialization locks</span></div><div class="ln "><span class="n">107</span><span class="c">  .hash-* .count-* .stale-* .stale-since-* .paused-* .wedge-escalations-* .seen-* .hb-surfaced-* .last-* .heartbeat-streak   watcher internals; never touch</span></div><div class="ln "><span class="n">108</span><span class="c">  .watch-triage.log  watcher&#x27;s absorbed-wake debug log (size-capped); never relied on, safe to delete</span></div><div class="ln "><span class="n">109</span><span class="c">  .last-watcher-beat watcher liveness beacon, touched every poll (including while absorbing benign wakes); guard scripts read it</span></div><div class="ln "><span class="n">110</span><span class="c">  .subsuper-* .supervise-daemon.*   sub-supervisor internals; never touch</span></div><div class="ln new"><span class="n">111</span><span class="c">visuals/             firstmate&#x27;s own fleet and operational visual aids (status boards, review dashboards); LOCAL, gitignored (section 9)</span></div><div class="ln "><span class="n">112</span><span class="c">.no-mistakes/        local validation state and evidence; gitignored</span></div><div class="ln "><span class="n">113</span><span class="c">`` `</span></div><div class="ln "><span class="n">114</span><span class="c"> </span></div></div></section><section><h2>AGENTS.md — section 9 &quot;Escalation and captain etiquette&quot; (new visuals/ convention)</h2><div class="code"><div class="ln "><span class="n">402</span><span class="c">- A real blocker or failure after the relevant playbook is exhausted.</span></div><div class="ln "><span class="n">403</span><span class="c">- Anything destructive, irreversible, or security-sensitive.</span></div><div class="ln "><span class="n">404</span><span class="c">- A needed credential or login.</span></div><div class="ln "><span class="n">405</span><span class="c"> </span></div><div class="ln "><span class="n">406</span><span class="c">Do not surface automatic fixes, retries, routine progress, or internal supervision mechanics.</span></div><div class="ln "><span class="n">407</span><span class="c">Batch non-urgent updates into the next natural reply.</span></div><div class="ln "><span class="n">408</span><span class="c">Use plain chat for a yes-or-no decision and `lavish-axi` only when several options or a structured report benefit from a visual surface.</span></div><div class="ln new"><span class="n">409</span><span class="c">Write every generated visual aid or artifact - a Lavish board, an HTML explainer, a dataviz page, a rendered interactive review surface - to a root-level `visuals/` directory, never buried in an internal agent directory such as `data/`, `.lavish/`, or a task folder, so the captain can find and share it.</span></div><div class="ln new"><span class="n">410</span><span class="c">A visual about a specific project belongs in that project&#x27;s own root `visuals/`, produced by a crewmate and landed through the project&#x27;s normal delivery path because firstmate never writes into a project clone.</span></div><div class="ln new"><span class="n">411</span><span class="c">Firstmate&#x27;s own fleet and operational visuals, such as status boards and review dashboards, go in this home&#x27;s root `visuals/`, which is private and gitignored.</span></div><div class="ln "><span class="n">412</span><span class="c">Whenever a PR is mentioned, include its full `https://...` URL before any shorthand reference.</span></div><div class="ln "><span class="n">413</span><span class="c">Mention cost as a courtesy when unusually much work is running, but never block on it.</span></div></div></section><section><h2>docs/configuration.md — operational home layout</h2><div class="code"><div class="ln "><span class="n">12</span><span class="c">The tracked code root contains the shared instruction, skill, documentation, workflow, and `bin/` surfaces, while each effective `FM_HOME` contains private operational directories.</span></div><div class="ln "><span class="n">13</span><span class="c">`data/` holds durable private fleet records such as the project and secondmate registries, captain preferences, optional shared captain preferences, learnings, backlog, briefs, and scout reports.</span></div><div class="ln "><span class="n">14</span><span class="c">`state/` holds volatile runtime records such as task metadata, append-only status events, endpoint signals, watcher and wake-queue coordination, away-mode state, generated X-mode artifacts, private secondmate config-reread generations with their retry and quarantine state, and parent-owned secondmate pending-reply records under `state/pending-replies/` (`bin/fm-pending-reply-lib.sh`).</span></div><div class="ln "><span class="n">15</span><span class="c">`config/` holds local gitignored operating choices, and `projects/` holds the local project clones that Firstmate reads but changes only through the guarded exceptions in `AGENTS.md`.</span></div><div class="ln new"><span class="n">16</span><span class="c">`visuals/` holds firstmate&#x27;s own fleet and operational visual aids such as status boards and review dashboards, private and gitignored like `data/` and `state/`, under the convention owned by `AGENTS.md` section 9.</span></div><div class="ln "><span class="n">17</span><span class="c"> </span></div></div></section><section><h2>.gitignore</h2><div class="code"><div class="ln "><span class="n">1</span><span class="c">projects/</span></div><div class="ln "><span class="n">2</span><span class="c">state/</span></div><div class="ln "><span class="n">3</span><span class="c">data/</span></div><div class="ln new"><span class="n">4</span><span class="c">visuals/</span></div><div class="ln "><span class="n">5</span><span class="c">.no-mistakes/</span></div><div class="ln "><span class="n">6</span><span class="c">.lavish/</span></div><div class="ln "><span class="n">7</span><span class="c">.fm-secondmate-home</span></div><div class="ln "><span class="n">8</span><span class="c">.DS_Store</span></div></div></section>

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info

• ℹ️ .agents/skills/bearings/SKILL.md:38 - .agents/skills/bearings/SKILL.md:38 still points at .lavish/*.html boards, which conflicts with the new root visuals/ convention. This was explicitly scoped as follow-on work (no skill output-path changes in this PR), so no change needed here — just ensure the PR description notes it as deferred, per the approved scope.

✅ **Test** - passed

✅ No issues found.

• git diff 6bcb381..0fa54fd reviewed for scope (only .gitignore, AGENTS.md, docs/configuration.md; no scripts/skills touched)
• mkdir -p visuals && touch visuals/fleet-status-board.html; git check-ignore -v visuals/fleet-status-board.html; git status --porcelain — new .gitignore:4 entry ignores a generated home-root visual and the worktree stays clean
• grep '^+' <diff> | grep '—' — no em dashes in added lines; verified one-sentence-per-line style
• Verified section placement: rule stated once in AGENTS.md section 9 (lines 409–411); section 2 layout block (line 111) and docs/configuration.md (line 16) reference section 9 as owner without duplicating the rule
• Searched tests/ and bin/ for assertions on the real repo .gitignore — none exist (tests use their own fixture .gitignore files), so no existing automated test covers or is broken by this change
• Rendered all four changed doc sections to HTML and captured a full-page screenshot via headless Chrome as reviewer-visible evidence

⚠️ **Document** - 1 info

• ℹ️ .agents/skills/bearings/SKILL.md:38 - .agents/skills/bearings/SKILL.md line 38 still cites .lavish/*.html boards as pickup pointers. Left as-is intentionally: lavish tooling still defaults to .lavish/, so the pointer stays accurate until output paths migrate; the author scoped .lavish/ path changes as follow-on work. Update this pointer to visuals/ in the same follow-up that moves the tooling defaults.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.