docs: add FORK.md documenting fork overlay and origin-only push boundary

[jokim1]

Intent

Create a tracked FORK.md at the repository root documenting how this fork works, so every agent in any worktree finds the fork rules without restating them in each brief.

Content requirements (docs-only; distill; do not copy captain-private policy or approval mechanics):

1. Fork model: origin = jokim1/firstmate; upstream = kunchenguid/firstmate. Default branch lila-main is an overlay (upstream main plus curated squash-commit patch stack), periodically rebased onto upstream main. Force-push expected and authorized ONLY for lila-main on the jokim1 fork, never other branches, never upstream.
2. Hard boundary: all PRs/pushes/merges target origin fork only. Anything touching kunchenguid/firstmate (PR, comment, close, issue, artifact cleanup) only on captain's explicit per-item instruction. Local clones enforce this: upstream and sanchith remotes have push URLs disabled and pushes fail loudly. This rule itself must be documented in FORK.md.
3. Reconciling upstream vs ours: new upstream work via rebasing overlay onto upstream main; owner script is data/patch-queue/rebase-lila-main.sh in the operator's private home (name the owner without documenting private contents). Patches carry retire-when and drop once upstream covers them. Conflicts never auto-resolved; rebase stops for deliberate human/supervised resolution.
4. What a rebase means for checkouts: overlay commit IDs rewrite; previously-updated checkouts cannot fast-forward and update tooling reports skipped (diverged) - expected. Fix is deliberate reset to new tip in a quiet window, not a merge and not a force anywhere else.
5. Keep short (~40-70 lines). Rules-of-the-road, not a tutorial. Do not duplicate AGENTS.md; link/point instead. No AGENTS.md edits. Optionally one short pointer elsewhere only if a natural anchor exists.

Constraints: PR target = origin fork (jokim1/firstmate) ONLY; upstream (kunchenguid/firstmate) is FORBIDDEN for any write. Captain approved this as a fork-only new-file docs patch; usual adversarial panel for fork-queue candidates waived (captain, 2026-08-15). Follow firstmate-coding-guidelines / repo style (one sentence per line, plain dashes, no agent co-authors).

Context for this relaunch: branch was rebased onto green origin/lila-main after CI-restoration PRs #5/#6/#7 landed; obsolete pre-existing-CI-fix commits that conflicted with those landings were dropped because main already covers them. Prior review ask-user about issues-only wording was answered and applied. Re-validate the existing open PR #4 through green CI.

What Changed

• Add a tracked FORK.md at the repo root that documents the fork model: origin (jokim1/firstmate) vs upstream (kunchenguid/firstmate), the lila-main overlay branch (upstream main plus a curated squash-commit patch stack, periodically rebased), and the rule that force-push is authorized only for lila-main on the jokim1 fork.
• Document the hard boundary that all pushes, PRs, and merges target the origin fork only, with any write to upstream gated on explicit per-item instruction and enforced locally by disabled push URLs on the upstream/sanchith remotes; also cover the operator-private rebase owner, patch retire-when/conflict handling, and how checkouts recover after an overlay rebase rewrites commit IDs.
• Register FORK.md in docs/documentation-audiences.json as an agent-runtime doc so audience classification and local-link checks recognize it.

Risk Assessment

✅ Low: Well-bounded docs-only change adding a single tracked FORK.md plus one audience-classification entry; content matches every required intent constraint, introduces no executable behavior, and the JSON stays valid.

Testing

I exercised the documentation-audience validation that CI itself runs — the structural checker (bin/fm-doc-audience-check.sh) and its test suite (tests/fm-documentation-audiences.test.sh) both pass, confirming FORK.md is registered and classified exactly once as an agent-runtime surface with all local links resolving. I mapped FORK.md's content against every required constraint in the intent (origin/upstream model, lila-main overlay and squash-patch stack, force-push authorized only for lila-main on the jokim1 fork, origin-only hard boundary with captain-gated upstream writes and disabled upstream/sanchith push URLs, rebase reconciliation naming data/patch-queue/rebase-lila-main.sh without private contents, retire-when patch drops, non-auto-resolved conflicts, and the checkout-divergence/reset-in-quiet-window guidance) and captured a rendered screenshot of the doc as the end-user surface. Scope is clean: only FORK.md and the audience inventory changed, AGENTS.md is untouched, and the file is 48 lines. PR #4 CI is passing with zero failures; at finalize time 8 of 12 checks were green and the remaining 4 broad behavior-serial suites were still running (no failures). No forbidden upstream writes occurred. Worktree left clean; evidence files kept in the dedicated evidence directory.

• Evidence: Rendered FORK.md (end-user doc surface) (local file: /var/folders/vx/kq2w6_xj1sq82jh1gtsjl0_m0000gn/T/no-mistakes-evidence/01M094BS1ZT2BEYX1XQ5RZ9RR6/FORK.md.preview.png)

Evidence: Rendered FORK.md (HTML preview)

<!doctype html><html><head><meta charset="utf-8"><title>FORK.md preview</title>
<style>
body{font-family:-apple-system,Segoe UI,Roboto,sans-serif;max-width:820px;margin:40px auto;padding:0 24px;color:#1f2328;line-height:1.55}
h1{border-bottom:1px solid #d0d7de;padding-bottom:.3em;font-size:2em}
h2{border-bottom:1px solid #d0d7de;padding-bottom:.3em;font-size:1.5em;margin-top:28px}
code{background:#eff1f3;padding:.15em .35em;border-radius:6px;font-size:85%}
a{color:#0969da;text-decoration:none} a:hover{text-decoration:underline}
p{margin:0 0 2px} .sp{height:12px}
.banner{background:#ddf4ff;border:1px solid #54aeff66;border-radius:6px;padding:10px 14px;font-size:14px;margin-bottom:24px}
</style></head><body>
<div class="banner">Rendered preview of repository-root <strong>FORK.md</strong> (48 lines) added on branch <code>fm/fm-fork-md</code>. This is the end-user surface every agent reads.</div>
<h1>This fork</h1>
<div class="sp"></div>
<p>This repository is a fork of <a href="https://github.com/kunchenguid/firstmate">kunchenguid/firstmate</a>.</p>
<p><code>origin</code> is <a href="https://github.com/jokim1/firstmate">jokim1/firstmate</a>.</p>
<p>The upstream remote is <code>upstream</code> and points at kunchenguid/firstmate for fetch only.</p>
<div class="sp"></div>
<p>Day-to-day agent work, agent instructions, and the always-loaded contract live in <a href="AGENTS.md">AGENTS.md</a>.</p>
<p>This file is only the fork overlay and remote boundary.</p>
<div class="sp"></div>
<h2>Overlay model</h2>
<div class="sp"></div>
<p>The default branch is <code>lila-main</code>.</p>
<p>It is an overlay: current upstream <code>main</code> plus a small curated stack of patches.</p>
<p>Each approved fork change lands as one squash commit on that stack.</p>
<p>The stack is periodically rebased onto current upstream <code>main</code>.</p>
<div class="sp"></div>
<p>Force-push is expected and authorized <strong>only</strong> for <code>lila-main</code> on the jokim1 fork.</p>
<p>Never force-push any other branch.</p>
<p>Never force-push to upstream.</p>
<div class="sp"></div>
<h2>Hard boundary: origin only</h2>
<div class="sp"></div>
<p>All pushes, pull requests, and merges target the origin fork (<code>jokim1/firstmate</code>) only.</p>
<div class="sp"></div>
<p>Anything that writes to kunchenguid/firstmate - PR, push, merge, comment, issue, or cleanup of artifacts there - happens only on the captain&#x27;s explicit per-item instruction.</p>
<p>Without that word, all upstream writes are forbidden.</p>
<div class="sp"></div>
<p>Local clones enforce the push half of this boundary:</p>
<p>the <code>upstream</code> and <code>sanchith</code> remotes have push URLs disabled, so any push there fails loudly.</p>
<div class="sp"></div>
<h2>Reconciling upstream vs ours</h2>
<div class="sp"></div>
<p>New upstream work arrives by rebasing the overlay stack onto upstream <code>main</code>.</p>
<p>The owner of that rebase is the operator-private script <code>data/patch-queue/rebase-lila-main.sh</code> in the operator&#x27;s private home (not this repo).</p>
<p>Do not reimplement or invent a second rebase path.</p>
<div class="sp"></div>
<p>Each patch carries a retire-when condition and is dropped once upstream covers it.</p>
<p>Conflicts are never auto-resolved: on conflict the rebase stops, and a human or supervised agent resolves deliberately.</p>
<div class="sp"></div>
<h2>What a rebase means for checkouts</h2>
<div class="sp"></div>
<p>A rebase rewrites overlay commit IDs.</p>
<p>Previously updated checkouts cannot fast-forward afterward; update tooling will report them skipped as diverged.</p>
<p>That outcome is expected.</p>
<div class="sp"></div>
<p>The fix is a deliberate reset to the new <code>lila-main</code> tip during a quiet window.</p>
<p>Do not merge to &quot;catch up&quot;.</p>
<p>Do not force-push anywhere except the authorized <code>lila-main</code> origin path above.</p>
<div class="sp"></div>
</body></html>

Evidence: Doc-audience checker output

$ bin/fm-doc-audience-check.sh
fm-doc-audience-check: ok surfaces=71 local_links=242

Evidence: PR #4 CI checks

summary: 8 passed, 0 failed, 4 pending, 12 total
Lint shell scripts: pass | Test coverage guard: pass | Behavior portable parallel 1/2: pass | Behavior tests (Herdr): pass | Stock macOS Bash snapshot compatibility: pass | Repo invariants: pass | Behavior portable serial 1-4: pending

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bin/fm-doc-audience-check.sh → ok surfaces=71 local_links=242 (FORK.md classified exactly once as agent-runtime; all local links resolve)
• bash tests/fm-documentation-audiences.test.sh → all 4 structural cases pass (exact-once classification, setup routing, required owner pointers, local-link resolution)
• Rendered FORK.md to HTML and captured a full-page screenshot to confirm the end-user doc surface and that all four required sections are present
• git diff --name-only cf49ebc..HEAD → only FORK.md and docs/documentation-audiences.json changed; AGENTS.md not touched; FORK.md is 48 lines (within the ~40-70 target)
• gh-axi pr checks 4 → 8 passed, 0 failed (Lint, Test coverage guard, Repo invariants, Herdr, macOS Bash snapshot all green; 4 broad serial behavior suites still running with no failures)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.