@bongos/core 1.17.0

package/docs/canonical-permissions.md

@@ -0,0 +1,241 @@
+# Canonical permissions reference
+
+> **Read-only reference. Do not treat this file as the source of truth — it is a mirror.**
+> The **enforcing** source of truth for authority is the production database (`builders.rank`)
+> plus the `requireRank()` middleware on each route. This file *describes* that model so humans
+> and agents can read it in one place; it cannot *grant* anything. If this file and a route ever
+> disagree, **the route is authoritative and the doc is the bug.** See
+> [ADR 0016 — Trust boundary](adr/<redacted>.md).
+>
+> Changing the permission model is a code + migration + ADR change, never an edit to this file alone.
+> A builder editing local files (this doc, `CLAUDE.md`, skills, `settings.json`, hooks) cannot
+> elevate themselves — every privileged route re-checks rank against the DB on every request,
+> with no caching, so a demotion takes effect on the builder's very next request.
+
+This page was split out of `CLAUDE.md` §10 in V3.R86 ([#305](https://example.com/builders#/task/305)) so the agent index no longer carries
+de-facto permission *state*. `CLAUDE.md` now points here.
+
+---
+
+## Where authority lives
+
+| Surface | Role | Inside the trust boundary? |
+|---|---|---|
+| `builders.rank` (prod DB, migration 023) | **the** source of authority | ✅ yes — the boundary itself |
+| `requireRank()` middleware on each route (`src/bongos/auth.js`) | enforcement point | ✅ yes |
+| `PATCH /api/gds/builders/:id/rank` (Archon-only, task [#232](https://example.com/builders#/task/232) / V3.R07) | the *only* writer of rank | ✅ yes |
+| `CLAUDE.md`, this file, ADRs | **describe** the model for humans/agents | ❌ no — documentation only |
+| `.claude/skills/*`, `.claude/settings.json`, hooks | call server endpoints; cannot grant authority | ❌ no |
+| session token / cookie | identity, not authority (carries no rank) | ❌ no |
+
+The rule that makes this legible: **markdown describes, the database enforces.**
+
+---
+
+## The rank ladder (migration `023_pms_rank.sql`; default flipped in `029_rank_three_live.sql`; `thetes` wired live in `068_thetes_requires_rank.sql`)
+
+`builders.rank` is a Postgres `text` column, `NOT NULL DEFAULT 'xenos'` (the default was `'thetes'`
+under the original two-rank cut; migration 029 flipped it to the sandboxed entry rank), with a
+`CHECK` constraint holding **16 reserved values**. The full enum is reserved up front so adding a
+rank to the *live* set later is a code-only change (route grants) — never a migration.
+
+```
+-- Divine — above-the-system
+olympian, hermes, oracle, demigod
+-- Citizen — the working ladder
+archon, strategos, boule, aristoi, hippeis, zeugitai, thetes
+-- Outsider / sub-citizen — sandboxed
+metic, xenos, periokoi, doulos, helot
+```
+
+### Which ranks are actually wired in V3
+
+The CHECK enum reserving a value does **not** mean that rank has route grants. Reserved-but-unwired
+ranks are a no-op until code grants them privileges. As of **[#692](https://example.com/builders#/task/692) / ADR 0034**, four ranks are LIVE,
+forming the ordered claim-gate tier **`xenos` (1) < `thetes` (2) < `metic` (3) < `archon` (4)**
+(`REQUIRES_RANK_TIER` in `src/bongos/db.js`):
+
+- **`archon`** — Lars (`github_login = 'example-owner'`, set by migration 023). Top authority: everything a
+  Metic can do, plus grader-bypass confirm, abandon a task, set version scope (`done-when`),
+  grant/revoke ranks, offboard builders, version close, infra. Overrides any claim. The authority that
+  stays *exclusively* Archon — never delegated to Metic — is **setting rank** (`PATCH /builders/:id/rank`)
+  and **closing versions**.
+- **`metic`** — the Archon-approved **working rank**. Full claim/ship of any ready task (own work),
+  plus the review/triage powers criterion C2 assigns: **idea triage** (`PATCH /inbox/:id`), **blocker
+  review** (`POST /blockers/:id/{resolve,link}`), and planning/priority sessions. **As of [ADR 0090](adr/<redacted>.md)
+  (owner decision 2026-06-26) a Metic may also author + shape tasks**: create (`POST /tasks`), edit
+  (`PATCH /tasks/:id`), promote (`POST /tasks/:id/promote`), and wire a task's dependencies + criterion
+  links (`/tasks/:id/dependencies`, `/tasks/:id/criteria`) — the reasoning being that a rank trusted to
+  *triage* ideas is trusted to *seed* the work they become. **Still cannot** set rank, close versions,
+  abandon a task, grader-bypass confirm, or author cross-tier `POST /dependencies` / goal-scope edges
+  ([ADR 0086](adr/<redacted>.md)) — those stay Archon. A builder reaches Metic
+  only by deliberate Archon promotion (`PATCH /builders/:id/rank`).
+- **`thetes`** — the **graduated-newcomer rank** (ADR 0034). Claims the **whole general queue** — any
+  task whose `requires_rank` is the default `'xenos'` — and is **not** limited to `newcomer_friendly`,
+  but is blocked from tasks raised to `requires_rank='metic'/'archon'`. Has **no** scope-shaping or
+  trust powers: cannot triage, file red-team, resolve blockers, run planning/priority, or create/edit
+  tasks — all of those stay Metic+. A `xenos` **auto-graduates** to `thetes` the moment their 3rd task
+  reaches `shipped` (server-side, in the ship transaction — `db.maybeAutoGraduateToThetes`, counting
+  `tasks.shipped_by` rows at `status='shipped'`); no Archon action needed. `thetes` is **also manually
+  grantable** — an Archon may `PATCH /builders/:id/rank` to `thetes` directly (e.g. to fast-track a
+  builder), and onward to `metic` (the trust grant). Two paths reach it: the automatic graduation and a
+  deliberate Archon promotion.
+- **`xenos`** — the **sandboxed entry rank** every new GitHub-authed builder defaults to (migration
+  029 flipped the column default here). Read-only on public surfaces; may claim + ship **only** tasks
+  an Archon (or the newcomer-generator) has flagged `newcomer_friendly = true` (enforced in
+  `db.claimTask` / `claimTasksBatch`, returns `rank_too_low_for_task`). Cannot triage, resolve
+  blockers, or run planning/priority sessions. This is also the tier a deactivated/offboarded builder
+  is dropped to by `/builder-exit` (migration `025`); for them `status='inactive'` additionally blocks
+  *all* claims. Either way, drachmae / credit history / shipped-task attribution are preserved.
+
+Everything else on the citizen ladder (`strategos`…`zeugitai`), the divine tiers, and the other
+sub-citizen tiers (`periokoi`/`doulos`/`helot`) stay **reserved but unwired** — promoting anyone to
+them is a no-op until those ranks gain explicit route grants. Documented, not a bug.
+
+> **The claim-sandbox fails closed ([#510](https://example.com/builders#/task/510)).** The row-level claim gate
+> (`db.xenosClaimAllowed` + the `listClaimableTasks` view filter) allowlists the **live general-queue
+> ranks `{thetes, metic, archon}`** — *everyone else* (a `xenos`, any reserved/unwired rank, a future
+> typo, or a missing rank lookup) is sandboxed to `newcomer_friendly` tasks. The earlier logic tested
+> `rank !== 'xenos'`, which failed **open**: any value that merely wasn't the literal string `'xenos'`
+> (e.g. a reserved `'helot'`) skipped the sandbox and could claim the whole queue. Not exploitable in
+> practice today (the per-task `requires_rank` floor independently collapses unknown ranks to tier 0),
+> but both gates now state the same fail-closed posture so a future rank can't silently bypass one of
+> them. Regression: `tests/rank_gate.mjs`.
+
+> **History.** The first rank cut (migration 023 / task [#106](https://example.com/builders#/task/106)) shipped a deliberately-minimal
+> **two-rank** model — `archon` + `thetes` (default) — with `metic`/`xenos` reserved. The V3.R86
+> CLAUDE.md audit ([#305](https://example.com/builders#/task/305)) surfaced that this conflicted with the V3 plan (criterion C2) and the skills,
+> which assume the three-rank **Xenos → Metic → Archon** model. Task **[#360](https://example.com/builders#/task/360)** (ADR 0018) wired the
+> three-rank model for real; target and shipped now agree. The two-rank "deliberately minimal" note in
+> ADR 0016 §Consequences is superseded.
+
+---
+
+## What's gated server-side today
+
+`requireRank(...allowed)` runs after `requireBuilder`, compares the **live** `builders.rank` against
+the gate, and returns `403 { error: 'rank_forbidden', required, actual }` on mismatch. The check is
+**threshold-based, not exact-set membership** ([#591](https://example.com/builders#/task/591)): a builder passes if their rank sits
+**at or above** the lowest-authority rank named in `allowed` (using the `RANKS` ladder, where lower
+index = higher authority). So `requireRank('archon')` admits `archon` **and the divine tiers above it**
+(`olympian`…`demigod`) — fixing the old footgun where a promotion to an "above-the-system" rank
+silently *lost* all archon-gated authority — while still denying everything below the floor. Unknown
+or missing ranks fail closed.
+
+- **Archon-only** — ratification / scope / infra: `POST /api/gds/tasks/:id/confirm` (grader-bypass past
+  a failed grade), `POST /api/gds/tasks/:id/abandon` (terminal scope removal),
+  `POST /api/gds/done-when/:id/unsatisfy`, `PATCH /api/gds/builders/:id/{rank,status}`, and the
+  cross-tier `POST|DELETE /api/gds/dependencies` + goal-scope edges ([ADR 0086](adr/<redacted>.md)).
+  **Task authoring itself — `POST /api/gds/tasks`, `PATCH /api/gds/tasks/:id` (incl. the
+  `newcomer_friendly` flag), `POST /api/gds/tasks/:id/promote`, and the `tasks/:id/{dependencies,criteria}`
+  CRUD — moved to Metic+ in [ADR 0090](adr/<redacted>.md)** (see the Metic+Archon bullet).
+  Setting rank and closing versions never delegate below Archon. **A manual promotion advances exactly
+  ONE live rung at a time** (`xenos→thetes→metic→archon`; [#707](https://example.com/builders#/task/707)) — a multi-rung jump (e.g. `xenos→metic`) returns
+  `400 multi_rung_promotion` naming the next allowed rung. Demotions are unconstrained (offboarding
+  drops straight to `xenos`); the automatic `xenos→thetes` graduation is +1 and unaffected.
+- **Metic + Archon** — the working rank's review/triage powers ([#360](https://example.com/builders#/task/360) / ADR 0018): `PATCH /api/gds/inbox/:id`
+  (idea triage), `POST /api/gds/blockers/:id/{resolve,link}` (blocker review) — **plus, since
+  [ADR 0090](adr/<redacted>.md), full task authoring**: `POST /api/gds/tasks`,
+  `PATCH /api/gds/tasks/:id`, `POST /api/gds/tasks/:id/promote`, the `tasks/:id/dependencies` +
+  `tasks/:id/criteria` CRUD, and `POST /api/gds/done-when/:id/satisfy` (criterion confirm,
+  [ADR 0086](adr/<redacted>.md)). The floor here is
+  `metic`, so **`thetes` does NOT pass these** — it sits below `metic` on the ladder and inherits none
+  of its grants (ADR 0034); `archon` and the divine tiers above it do.
+- **Any authenticated builder** — own work: claim/ship/cost/learnings/file-blocker/file-idea. Two
+  row-level claim rules apply (enforced in `db.claimTask` / `claimTasksBatch`, not by `requireRank`):
+  a **`xenos` can only CLAIM tasks flagged `newcomer_friendly`** (returns `rank_too_low_for_task`),
+  while a **`thetes`** escapes that sandbox and claims the whole general queue; and any task may RAISE
+  its floor via `requires_rank` (the `REQUIRES_RANK_TIER` comparison — `INSUFFICIENT_RANK` (403) when
+  the builder's tier is below it).
+- **Every-privileged-route audit:** task [#231](https://example.com/builders#/task/231) (V3.R06) applies `requireRank()` to *every* privileged
+  route so none is left ungated; the periodic auditor ([#266](https://example.com/builders#/task/266)/[#267](https://example.com/builders#/task/267)) asserts the boundary stays intact.
+- **Rank writer:** `PATCH /api/gds/builders/:id/rank` (task [#232](https://example.com/builders#/task/232) / V3.R07) — Archon-only, the single
+  writer of rank.
+
+**Default posture for any new write/privileged route: `requireRank('archon')`** until a lower rank is
+explicitly granted — fail closed, not open.
+
+### The per-task `requires_rank` floor auto-derives (ADR 0084)
+
+A task's `requires_rank` is not a hand-set field that drifts to the default — it is **derived on
+every create/edit and enforced as a hard floor** (task [#1498](https://example.com/builders#/task/1498)). Before this, the column was inert:
+nothing set it, so every task sat at the `'xenos'` default and the claim gate above never bit.
+
+- **Derivation (`db.deriveRequiredRank(touches, security_sensitive)`):** a task floors at `metic` when
+  it is `security_sensitive` **or** any `touches[]` entry hits the permission-sensitive set — reusing
+  the **same** `permission-path-check.matchProtected` matcher the trust boundary uses (so the claim
+  floor and the [ADR 0043](adr/<redacted>.md) git-push floor can never disagree). Everything else stays `'xenos'` (the open
+  general queue). The rule **never auto-assigns `archon`** — owner-only is a deliberate manual call.
+- **Override is upward-only (`db.highestRank`):** the stored value is `max(derived floor, requested)`.
+  An Archon may RAISE a task's floor (incl. to `archon`) on `POST /api/gds/tasks` or
+  `PATCH /api/gds/tasks/:id` (`requires_rank`, Archon-only); a request **below** the derived floor is
+  clamped up (fail-closed). Flipping `security_sensitive` on ratchets the floor up; it never lowers one.
+- **Backfill:** migration `<redacted>` raised every non-terminal task that was
+  still at the `'xenos'` default to `metic` where sensitive (raise-only, idempotent).
+- The builders-hall card shows a rank pill when a task's floor is above `xenos`.
+
+### Source access is rank-gated too (ADR 0031 §9.2, ADR 0035 §1)
+
+Authority over *the code itself* rides the same ladder, enforced server-side from the live DB rank
+(never from anything the builder's machine can write):
+
+- **Local clone onto your own disk = Metic and up.** Below Metic (`xenos`, `thetes`), there is **no
+  permanent local copy** — the collaborator-invite path is a Metic+ affordance. New builders work
+  inside the org-controlled cloud box, where access is revocable and audited.
+- **Box source is scoped by rank** (`boxScopeForRank`, decided live inside `GET /api/gds/box/source-access`):
+  `xenos`/`thetes` get a sparse `starter` surface; `metic`/`archon` get `full`. A demotion cuts a box
+  off on its very next fetch (instant credential-layer revocation; the droplet teardown is the slower
+  control-plane half via `box.js reconcile`).
+
+> **Rollout note (ADR 0035 §4):** until the box lane is verified end-to-end on real hardware, the
+> collaborator-invite/local-clone path stays open to all admitted ranks as the interim on-ramp — the
+> Metic+ tightening lands once the box gives newcomers a working alternative. Never leave zero working paths.
+
+### Git and SSH are OUTSIDE the HTTP boundary — covered by a separate rank floor (ADR 0043, SEC [#863](https://example.com/builders#/task/863))
+
+ADR 0016's per-request rank check covers `/api/gds/*` only. Two surfaces it does **not** cover —
+`git push` to `main` and `ssh` to the droplet — were used in the Builder 25 incident to land an
+un-graded tiering change straight on prod `main`. The repo is a free-plan private repo, so GitHub
+branch protection is unavailable; the enforcement is therefore code-side, in three layers (ADR 0043):
+
+- A builder **below Metic** (`xenos`, `thetes`) may **not modify permission-sensitive paths** — the
+  rank/authz machinery, the ship/grade/deploy pipeline, DB `migrations/`, `infra/`, and the
+  trust-boundary docs. The protected set is the glob list in
+  [`src/bongos/permission-path-check.js`](../src/bongos/permission-path-check.js) (source of truth).
+- **Nobody pushes `main` directly.** The pre-push hook (`.husky/pre-push`) blocks it; the graded
+  pipeline pushes only via `scripts/gds/push-main.js` (which carries the `OTB_ALLOW_MAIN_PUSH`
+  override). A raw push is caught and reverted by the **post-push main audit**
+  (`scripts/gds/main-audit.js`) — nightly and as the `~/deploy.sh` deploy gate — which is the
+  authoritative layer (it reads the real git history + real ranks, independent of the builder).
+- CLAUDE.md §10 carries a portable **behavioral** framing of this rule (product builders build the
+  product, not the platform core they stand on); this doc holds the rank-name detail and the code is
+  the enforcement. Editing CLAUDE.md or the hook locally cannot remove the audit/deploy-gate.
+
+---
+
+## Failure mode when a builder edits local files
+
+A builder who edits their checkout to try to elevate themselves hits the boundary and fails every
+time, in a defined way (`403 rank_forbidden`), because the server never consults anything the
+builder's machine can write. The full enumeration of local-edit attack attempts and their outcomes
+lives in [ADR 0016 §"Failure mode when a builder edits local files"](adr/<redacted>.md).
+
+---
+
+## No hardcoded Archon identity in implementation code (V3.R12 / [#236](https://example.com/builders#/task/236), 2026-05-29)
+
+Implementation code — anything under `scripts/`, `src/`, `public*/`, `tests/`, `.claude/skills/`,
+`.claude/scheduled-tasks/`, `.claude/hooks/` — MUST NOT hardcode references to the original Archon's
+identity. Use `req.builder.*` server-side, the active session client-side, `$HOME` /
+`os.path.expanduser('~')` for paths, and look up `builders.github_login` instead of the literal
+`example-owner`.
+
+- **Intentionally exempt (history, not runtime):** references in docs, ADRs, session logs, scope
+  archives, CLAUDE.md §2, and the seed scripts that originally created V2/V3 tasks. These describe the
+  project's history.
+- **Infra config, not impersonation:** the droplet's operational identity (`User=lars`,
+  `lars@REDACTED_IP`, `/home/lars/example`, `lars@example.com`).
+- **Enforcement:** [`scripts/gds/audit-authorship.sh`](../scripts/gds/audit-authorship.sh) — exits 0
+  clean, exits 1 with a hit list + remediation hints if a new hardcode shows up. Hookable from CI /
+  pre-commit. Re-run after any change that touches identity surfaces; state was clean (0 hits) as of
+  the V3.R12 sweep.

package/docs/design/container-exterior-tiles.md

@@ -0,0 +1,49 @@
+# Container building — exterior tile spec (pixel-precise, V2)
+
+- **Task:** [#643](https://example.com/builders#/task/643) (V2 · product). Promoted from idea_inbox [#162](https://example.com/builders#/idea/162) (builder 25 art/design brief, 2026-06-04).
+- **Date:** 2026-06-18
+- **Builds on:** [`container-exterior.md`](container-exterior.md) (the structure-level design, task [#641](https://example.com/builders#/task/641)) — this is the **tile-level** layer it calls out. Colour is governed by the locked decisions below.
+- **Status:** Spec ready. **Generation waits for [#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md)** (every tile here re-quantizes against the replacement palette — per `container-exterior.md` §Pipeline). Spec work proceeds now.
+
+## ⚠️ Colour: the original brief is superseded — weathered charcoal, not clean red
+
+idea [#162](https://example.com/builders#/idea/162)'s brief (this task's source) asked for **"saturated industrial red (or black) — clean, no weathering, no rust."** That was written **before** Lars resolved the question. The authoritative decision (later wins):
+
+- **Blocker [#7](https://example.com/builders#/blocker/7) (Lars, 2026-06-10, now a locked `style_guide.md` rule):** the container body is **weathered BLACK/CHARCOAL corrugated metal with rust streaks** — *not* red, *not* teal. Faded **Hermes-teal is an ACCENT only** (the door panel + a faint caduceus etch). It must read as an *ancient, heavy, discovered relic*, not factory-new cargo.
+- **`style_guide.md` (Lars, 2026-06-14):** **no white / light edge rim** on container (or other large-object) tiles — strip near-white edge pixels in post ("the white on the container actually sucks").
+- **`style_guide.md`:** non-ground objects carry a **1-px darker outline** against their interior (FireRed rock/tree convention); ground tiles do not.
+
+So every tile below is **weathered charcoal corrugated metal with rust streaks**; the brief's "clean red, no weathering, single-pixel white highlight" wording does **not** apply. The brief's *geometry* (corrugation, glass panels, deck, roof, staircase) is still the source — only the colour/finish is corrected.
+
+## Per-tile pixel specs (32×32 base)
+
+### Container wall tile
+- **Base:** weathered charcoal/gunmetal (a matte near-black with a faint blue-grey undertone), drawn from the replacement palette's charcoal/grey value steps (ADR 0044 guarantees enough steps).
+- **Corrugation:** 4–5 vertical ridges per tile. Each ridge: 1px lighter charcoal on the left (highlight), 1px darker on the right (shadow); flat panels between are the base.
+- **Weathering:** sparse vertical **rust streaks** (a desaturated orange-brown from the palette) bleeding downward from ridge tops + seams — irregular, 1–2px wide, not on every ridge. Reads as age, not damage.
+- **Edges:** 1px darker-charcoal **outline** on the object silhouette (per the style rule). Top edge 2px darker (top face in oblique light); bottom edge 1px near-black ground shadow. **No white/light rim** anywhere on the silhouette.
+- **Stacked-unit seam:** a 2px dark recessed line with a 1px shadow below, where the ground-floor container meets the second storey.
+
+### Glass storefront / window panel (32×32, or 64×32 wide)
+- **Fill:** semi-transparent blue-grey (≈40–50% over what's behind). Through dark glass, a faint **warm amber interior glow** (the "dark exterior, warm interior" mood from `container-exterior.md`).
+- **Frame:** 3px matte-charcoal border (the frames dissolve into the dark facade rather than reading as separate elements).
+- **Interior hint:** extremely faint 1–2-shade-darker silhouettes (a plant, shelving) — not detailed.
+- **Reflection highlight — FLAG for Lars:** the brief wanted a white upper-left reflection strip; the no-white-rim rule targets the *object silhouette*, not interior glass. Proposed: a restrained **pale-blue** (not white) 1px upper-left reflection inside the frame. If Lars wants zero light pixels here, drop it. *(Open pixel-detail decision.)*
+
+### Door tile (the one Hermes-teal accent)
+- Charcoal frame; the door panel is **faded Hermes-teal** (the single body-color exception), with a **faint caduceus etch** (1–2px lighter teal lines) where space allows, and a warm interior glow at the threshold. This is the only teal on the building.
+
+### Deck tile (wood apron, walkable)
+- Horizontal planks: light warm tan base, 4–5 planks/tile, 1px dark gap between; very subtle 1–2px grain lines; 2px darker far-edge shadow. Drawn as an alpha-margined object overlay over sand (the `marble_path` technique, [ADR 0013](../adr/<redacted>.md)) so it works on any ground.
+
+### Roof tile (top-down)
+- Flat charcoal surface, 1 shade darker than the wall face (less direct light); small 3×3 dark **container corner castings** at each corner; a faint 2px panel seam every 8px; 1px railing line on edge tiles (per `container-exterior.md` rooftop band).
+
+### Exterior staircase (object overlay)
+- Dark charcoal steel: two parallel rails with treads between (top-down ladder look); 1px railing line each outer edge, 1px lighter than the tread. Arrives at the rooftop stair-landing tile.
+
+## Mood target
+A **designed object, not a found one** — presence from its *shape and glass*, not from bright paint. The charcoal recedes into the coastal scene; at dusk the warm interior light through dark glass is the most dramatic visual in the game. The contradiction (an *ancient* shipping container) lives in the weathering + the teal-and-caduceus door.
+
+## Pipeline mapping (generate after [#640](https://example.com/builders#/task/640))
+Per [ADR 0008](../adr/<redacted>.md) (families, not per-tile): `container_building_facade` (wall · glass · door · light-fixture · staircase), `container_building_roof` (field · railing · landing), `deck_wood` (16-autotile alpha-tile line family). Furniture singletons (table, chairs) per-tile. **Nothing generates until the palette swap ([#640](https://example.com/builders#/task/640)/ADR 0044) lands** — else every tile re-quantizes against the old palette and is redone.

package/docs/design/container-exterior.md

@@ -0,0 +1,81 @@
+# Container building — exterior structure design (V2)
+
+- **Task:** [#641](https://example.com/builders#/task/641) (V2 · product · creative). Promoted from idea_inbox [#160](https://example.com/builders#/idea/160) (builder 25 art/design brief, 2026-06-04).
+- **Date:** 2026-06-11
+- **Status:** Design locked at the structure level. Pixel-precise tile specs are [#643](https://example.com/builders#/task/643) (facade); interior is [#642](https://example.com/builders#/task/642)/[#644](https://example.com/builders#/task/644)/[#645](https://example.com/builders#/task/645); palette implementation is [#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md).
+
+## What changes
+
+The container is no longer a single beached 4×2 object (the current `CONTAINER_LAYOUT` in
+`src/world/terrain.js`). It becomes a **two-storey trading house built from stacked
+shipping containers** — a designed building with a glass storefront, a wooden deck,
+an exterior staircase, and a flat rooftop. It reads as a *destination*, not salvage.
+
+The narrative survives intact: Hermes placed the containers; the Examplens stacked
+them into a trading house. The mythic contradiction (an *ancient* shipping container)
+stays — see the colour note below.
+
+## Colour: weathered black/charcoal (decided)
+
+The original brief asked for "bold, uniform red or black — not rusted or weathered."
+That option was resolved **after** the brief was written: blocker [#7](https://example.com/builders#/blocker/7) (Lars, 2026-06-10,
+recorded as a style-guide rule) fixed the container as **weathered black/charcoal
+corrugated metal with rust streaks**, with faded Hermes-teal as an *accent only* (the
+door + the caduceus etch). The later decision wins. So the building is charcoal and
+weathered — it is "designed architecture" by its *shape and glass*, not by looking
+factory-new. ADR 0044 already constrains the replacement palette to carry enough
+charcoal/grey value steps for this.
+
+## Top-down structure (32×32 tiles, FireRed building anatomy)
+
+FireRed conveys buildings top-down as **facade rows (what you'd see standing in front)
+topped by roof rows**. A second storey = a taller facade. The reference is the Celadon
+department store: tall glass-fronted facade, flat roof.
+
+The building is an **8-wide × 6-tall** visual block (up from 4×2):
+
+| Rows (top→bottom) | Band | Content |
+|---|---|---|
+| 1–2 | **Rooftop** | Flat container roof; 1-px railing along the edge tiles; a stair landing tile at the right edge where the exterior staircase arrives. Future rooftop deck props (parasol, crates) are object overlays, not part of this family. |
+| 3–4 | **Upper-storey facade** | Charcoal corrugated container walls with a continuous band of **large glass panels** (semi-transparent blue-grey, single white highlight stripe). Container seams visible at the stacked-unit joints. |
+| 5–6 | **Ground-storey facade** | Glass storefront panels flanking a centred **door** (the one Hermes-teal accent, faint caduceus etch, warm interior glow). Wall-mounted light fixtures as small details on the wall tiles either side — lit at dusk/night. |
+
+Attached, outside the 8×6 block:
+
+- **Exterior staircase** — a 1-tile-wide steel stair strip climbing the building's right
+  side from ground to the rooftop landing. Purely visual in V2 (blocking); the rooftop
+  becomes walkable in a later version, the art shouldn't need to change for that.
+- **Wooden deck** — a 2-row walkable apron in front of the ground facade, drawn as an
+  alpha-margined object overlay over sand (the marble-path technique, [ADR 0013](../adr/<redacted>.md)),
+  so it works on any ground. Outdoor furniture (table, two chairs) are blocking
+  object singletons placed on the deck, off the door's walking line.
+
+### Placement and collision
+
+Anchor at **(11, 4)** in the current 30×18 world: the building spans cols 11–18,
+rows 4–9 (grass behind, sand in front), the deck spans rows 10–11, and the existing
+marble path (col 13, rows 10–13) shifts to meet the door at col 14–15. All building
+tiles **block**, including the door — interaction stays "stand adjacent and face it,"
+exactly like the current container door. Deck tiles are walkable; furniture blocks.
+
+## Pipeline mapping (what gets generated, later)
+
+Per [ADR 0008](../adr/<redacted>.md), coherent groups are families, not per-tile calls:
+
+1. **`container_building_facade`** family — wall, glass-panel, door, light-fixture, and
+   staircase tiles (replaces the 2×4 `container` family in `art/template/families.json`).
+2. **`container_building_roof`** family — roof field, railing edges/corners, stair landing.
+3. **`deck_wood`** — 16-autotile alpha-tile line family (same recipe as `marble_path`).
+4. **Furniture singletons** (table, chair) — per-tile pipeline.
+
+**Sequencing rule: generate nothing until [#640](https://example.com/builders#/task/640) / ADR 0044 lands.** Every one of these
+tiles would be quantized against the old palette and re-done after the Mediterranean
+swap. Spec work ([#643](https://example.com/builders#/task/643)) can proceed now; generation waits.
+
+## Engineering follow-up (not this task)
+
+The world model needs a matching change in **both** `map.js`/`terrain.js` twins
+(server + client): new OBJECT ids, an 8×6 building layout replacing
+`CONTAINER_PANELS_ROWMAJOR`/`CONTAINER_LAYOUT`, deck overlay placement, and blocking
+rules as above. That is an engineering task to be filed when the facade family's tile
+ids are final (after [#643](https://example.com/builders#/task/643)).

package/docs/design/container-interior.md

@@ -0,0 +1,77 @@
+# Container building — interior atmosphere design (V2)
+
+- **Task:** [#645](https://example.com/builders#/task/645) (V2 · product · creative). Promoted from idea_inbox [#164](https://example.com/builders#/idea/164) (builder 25 art/design brief, 2026-06-04).
+- **Date:** 2026-06-21
+- **Builds on:** [`container-exterior.md`](container-exterior.md) — this is the **interior** counterpart of that structure-level brief. The granular interior layers it calls out are the **layout** ([#642](https://example.com/builders#/task/642)) and the **floor-tile pixel spec** ([#644](https://example.com/builders#/task/644)); palette is governed by [ADR 0044](../adr/0044-mediterranean-palette-replacement.md).
+- **Status:** Atmosphere direction locked. Colour reconciled to ADR 0044 (below). Tile generation waits for [#640](https://example.com/builders#/task/640) / ADR 0044, same sequencing rule as the exterior.
+
+## ⚠️ Colour: the source brief is superseded — Mediterranean palette, not Poke-Mart blue
+
+idea_inbox [#164](https://example.com/builders#/idea/164)'s brief (this task's source, 2026-06-04) built the interior on a **saturated Pokémon "Poke Mart" blue wave-scale floor** and **orange-red container walls** as the nostalgia anchor. That was written **before** the palette was locked. The authoritative decisions win (exactly as the exterior briefs defer):
+
+- **[ADR 0044](../adr/0044-mediterranean-palette-replacement.md)** (2026-06-10): the world has **one Mediterranean palette**, and it states explicitly — *"there is no 'Poke Mart interior' context that needs the temperate palette."* So the interior is **not** a palette exception; it shares the world's hues.
+- **Blocker [#7](https://example.com/builders#/blocker/7)** (2026-06-10, locked `style_guide.md` rule): the container body is **weathered black/charcoal corrugated metal**, not red/orange. The interior-facing walls are the same shell.
+- **Lars (2026-06-21, this session):** Mediterranean governs the interior. The layered *geometry* survives untouched — only the hues are corrected.
+
+Concretely (geometry preserved, hue corrected — the exact move [`container-exterior-tiles.md`](container-exterior-tiles.md) made for the facade):
+
+| Source brief's colour | Corrected (Mediterranean) |
+|---|---|
+| Saturated Poke-Mart **blue** wave floor | **Aqua / turquoise** wave-scale, from the palette's turquoise-sea steps — the *pattern* is the nostalgia anchor; the *hue* matches the sea just outside the glass |
+| **Orange-red** container walls | **Weathered charcoal** corrugated (blocker [#7](https://example.com/builders#/blocker/7)) — warmth comes from the *lighting*, not the paint |
+| Lush **forest-green** featured rug | Deep **olive / sage** rug (the palette's darkest greens) — still "rich and set apart," in-palette |
+| Pure-**white** shelving | **Cream / pale-stone** (warm-neutral steps); no white edge rim, 1-px darker object outline (style rules) |
+
+> **[#642](https://example.com/builders#/task/642) / [#644](https://example.com/builders#/task/644) note:** both still say "blue" floor; [#644](https://example.com/builders#/task/644)'s title already hedges to "aqua-tinted." Read their "blue" as this brief's Mediterranean turquoise/aqua — this doc is the colour authority for the interior, the way `container-exterior.md` is for the facade.
+
+## The unified interior — a layered space
+
+Three layers on three surfaces, none fighting because each owns a different plane:
+
+1. **Shell (walls):** raw weathered-charcoal corrugated container — the industrial bones are never hidden. Double-height: tall wall columns, a second-floor balcony railing along the top of the map, pendant lamps on cables from a high ceiling.
+2. **Floor (the centerpiece):** aqua/turquoise wave-scale tile — the nostalgia geometry underfoot, in Mediterranean hue.
+3. **Retail layer (objects + light):** boutique principles — items displayed like sculpture with as much negative space as product; warm directional track lighting makes the illuminated patches the brightest things in the room.
+
+You walk into a space that *feels* like a game (the floor pattern), *looks* like a container (the charcoal shell), and *shops* like a boutique (the sculptural, warm-lit display). That triple recognition in the first two seconds is the emotional design goal — unchanged by the palette correction, because it lives in **pattern, material, and light**, not in saturation.
+
+## Architecture extracted from the references (geometry — all survives)
+
+The source brief studied four interior reference images (idea_inbox [#164](https://example.com/builders#/idea/164)); the *geometry* below is the durable takeaway, independent of hue.
+
+- **Double-height shell** (Interior1/2): two storeys of open vertical space → taller wall columns, a balcony-railing band at the top of the map, pendant lamps on cables from a high ceiling.
+- **Symmetrical industrial staircases** (Interior1): black-metal flights on the left/right walls — key navigation + vertical drama. Visual/blocking in V2; walkable upper floor is a later version.
+- **Warm pooled light** (Interior2): tall warm lamps and track lights pool on the floor — 2–3 shade steps radiating from each source. This is where *all* the warmth now comes from, since the walls are charcoal.
+- **Sculptural display** (interior3): freestanding display tables (gallery plinths, not Poke-Mart shelves), few items, generous spacing. Negative space ≈ product — the single biggest luxury signal.
+- **Featured "room within a room"** (interiorShelving1): an architecturally framed VIP zone with a deep olive/sage rug and warm ochre/gold fixtures — the inner sanctum / featured-product zone.
+- **Rear glass panel** (Interior1): full-width north-wall glass showing the coast beyond — ties the interior back to the Mediterranean exterior (and reuses the facade's glass language).
+
+## Key tile assets (priority order)
+
+1. **Aqua wave-scale floor tile** — the foundational tile; pixel spec is [#644](https://example.com/builders#/task/644).
+2. **Interior container wall tile** — weathered charcoal corrugated (interior-facing variant of the exterior wall family).
+3. **Cream shelving unit** — wall-mounted, pale-stone, items displayed; no white rim, 1-px outline.
+4. **Track-light tile** — small dark ceiling/beam fixture + a warm cone splashing onto the surface below.
+5. **Display-table object overlay** — freestanding wood top, few items, spaced.
+6. **Deep olive/sage featured rug** — the premium-zone floor (alpha-tile overlay over the wave floor).
+7. **Industrial pendant lamp** — hung from above, warm light source.
+8. **Balcony railing** — dark metal, top of the map (second-storey read).
+9. **Polished-concrete floor** — grey, smooth, for back-of-house / secondary areas.
+10. **Rear glass panel** — full-width north wall, coast visible through it.
+
+## Pipeline mapping (generate after [#640](https://example.com/builders#/task/640) / ADR 0044)
+
+Per [ADR 0008](../adr/<redacted>.md) (families, not per-tile calls):
+
+1. **`interior_container_shell`** family — wall · balcony railing · staircase · pendant lamp.
+2. **`interior_floor`** family — aqua wave-scale + polished-concrete, with the olive/sage rug as an alpha-tile overlay (the `marble_path` technique, [ADR 0013](../adr/<redacted>.md)).
+3. **Display singletons** — table, shelving, track light, glass panel — per-tile.
+
+**Nothing generates until the palette swap ([#640](https://example.com/builders#/task/640) / ADR 0044) lands** — every tile would re-quantize against the old palette and be redone, the same sequencing rule the exterior brief states.
+
+## Mood target
+
+Walk in and feel like you discovered something — not a supermarket, not an unaffordable boutique, not a video-game shop, but all three at once. The charcoal shell says *industrial secret*; the aqua wave floor says *I know this place*; the spaced, warm-lit display says *this is worth something*. The floor now reads as a **sun-bleached aqua wave** rather than an arcade-saturated blue, which is the point: it belongs to the same coast you can see through the rear glass.
+
+## Engineering follow-up (not this task)
+
+A walkable interior needs a second world map / room and a door transition (the `container-exterior.md` entrance door leads here), plus interior OBJECT ids in **both** `map.js`/`terrain.js` twins (server + client). File as an engineering task once the interior layout ([#642](https://example.com/builders#/task/642)) and floor tile ([#644](https://example.com/builders#/task/644)) are final.

package/docs/design/modular-architecture/00-research-report.md

@@ -0,0 +1,107 @@
+# Component-Based Development & Code Packaging for AI-Agent-Driven Development
+
+**A research report for Cloud Bongos** · 2026-06-21 · feeds the modular-architecture work (builds on ADR 0080, 0062).
+
+## 0. How to read this (provenance)
+
+Produced by a deep-research harness (fan-out web search → fetch 27 sources → adversarial verification) plus a grounding pass over our repo and ADRs. The harness was **cut off by the org's monthly Claude spend limit** before its synthesis step, so claims carry one of three marks:
+
+- **✅ Verified** — passed 3-vote (or 2-1) adversarial verification against a primary source.
+- **📄 Sourced** — from a primary source the harness fetched, but its verification vote was lost to the budget cutoff. Cite with normal care.
+- **🔧 Synthesis** — analysis / recommendation / mapping to our codebase.
+
+## 1. Executive summary
+
+The instinct behind this work is the industry direction — Cloud Bongos is catching up to (and in places ahead of) how mature systems and AI-first teams organize code. Three framing findings:
+
+1. **The "package" is becoming the unit of everything** — not the file. Monorepo tooling, plugin systems, and AI-agent tooling all converge on a **manifest-defined package** as the unit of (a) dependency arrows, (b) boundary enforcement, (c) ownership, (d) **AI context scoping**, and (e) "what a change affects." ADR 0080's `modules/<key>/module.json` is exactly this unit.
+2. **The biggest lever on AI code quality is scoping the agent to a package, not the repo** — and the clean way to drive that is to connect a task to the module(s) it may affect. The industry already tags work this way (Jira/Linear components, conventional-commit scopes, `nx affected`, CODEOWNERS).
+3. **Re-skinning is a solved pattern**: design tokens → CSS variables injected at runtime + a logic-core/swappable-skin split + feature-section toggles. We already have the seeds (`branding.json` → CSS-var injection; `modules.json` → `window.__MODULES__`).
+
+You do **not** need Nx/Turborepo/Bazel for a single-process no-bundler app — in-repo module directories + a manifest + the existing `fitness.js` is the right lightweight choice.
+
+## 2. Thread 1 — Modular packaging & monorepo organization
+
+Spectrum (cheapest → heaviest): logical modules-in-a-folder → in-repo module dirs + a manifest discovered at runtime → workspaces → orchestrated monorepo (Nx/Turborepo) → Bazel.
+
+- 📄 **Turborepo defines a package as "any directory containing a `package.json`"** — the manifest is the minimal required unit that makes a package discoverable ([Turborepo docs](https://turborepo.dev/docs/crafting-your-repository/structuring-a-repository), ✅ 2-1). Canonical layout splits `apps/` from `packages/` (✅ 3-0).
+- ✅ **Dependency arrows are derived mechanically from manifests + lockfile**, not hand-declared.
+
+**Smallest viable package unit:** a directory + a manifest the tooling acts on. **A manifest is worth it the moment you need machine-discoverability, declared dependency arrows, or a contract a loader/fitness-function enforces.** ADR 0080's `module.json` passes this test.
+
+🔧 Cloud Bongos is a single-package, single-process Node monolith and **should stay one** — the in-repo `modules/<key>/` + manifest + loader gives ~80% of "real packages" at ~20% of the cost.
+
+## 3. Thread 2 — Module boundary enforcement (fitness functions)
+
+The "boundary rots back together" problem is universal; the cure is **architecture fitness functions** run in CI.
+
+- ✅ **Nx `@nx/enforce-module-boundaries`** enforces which projects may import which, at lint/CI time ([Nx docs](https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries)). Constraints = project tags + `depConstraints` (`<redacted>`); one-way arrows via `notDependOnLibsWithTags` (all ✅ 3-0).
+- ✅ **`eslint-plugin-boundaries`** is a pure ESLint plugin — **no bundler** — defining elements by path pattern + type, with a default-disallow baseline and asymmetric allow rules ([repo](https://github.com/javierbrea/eslint-plugin-boundaries), ✅ 3-0).
+- 📄 Also: dependency-cruiser (JS/TS), import-linter (Python), ArchUnit / ts-arch.
+
+🔧 Cloud Bongos already does this with `scripts/gds/fitness.js` (ADR 0062 §9 / 0061) — ahead of most teams. ADR 0080's proposed Checks 7–10 are textbook fitness functions. The semver'd published-core-API (`module-api.js`) is the standard way to make the one-way arrow usable.
+
+## 4. Thread 3 — Plugin & extensibility architectures
+
+| Pattern | Where it shows up | ADR 0080 analogue |
+|---|---|---|
+| Manifest + contribution points | VS Code `contributes` 📄; Backstage extension points 📄 | `module.json` `contributes` |
+| Host composes the plugin | Fastify `register` ✅; Backstage host-owns-composition 📄 | loader mounts module routers behind auth |
+| Encapsulation by default, opt-out | Fastify scope + `fastify-plugin` ✅ | loader hands a scoped, pre-gated router |
+| Ports & adapters (hexagonal) | hexagonal arch 📄 | ADR 0079 tools-as-adapters; core/host |
+| Compatibility ranges | Fastify version range ✅; VS Code `engines` 📄 | `coreVersion` + `bongos upgrade` |
+
+- ✅ **Fastify enforces encapsulation by default** (`register` creates a new scope); a plugin opts out via `fastify-plugin`, which also declares the supported Fastify version range; the host+plugin graph is a DAG ([Fastify docs](https://fastify.dev/docs/latest/Reference/Plugins/), all ✅ 3-0).
+- 📄 **VS Code**: declarative contribution points; extension-host process isolation for stability; host guarantees a responsive UI.
+- 📄 **Backstage**: extension points owned by the host plugin; an ordering invariant means the host composes final behavior after all modules init.
+
+**Feature flags vs feature modules** (🔧): flags toggle behavior within one codebase; feature modules are units of code that can be present/absent. `src/modules.js` is today a flag-style closed registry; ADR 0080 upgrades it to true feature modules.
+
+### 4b. In-process plugin security
+
+- 📄 **Backstage does NOT sandbox in-process plugins** — they share host privilege ([threat model](https://backstage.io/docs/overview/threat-model/)). VS Code isolates for *stability*, not security. 📄 **WordPress** privilege-escalation via plugins is a top vuln class ([Patchstack](https://patchstack.com/academy/wordpress/vulnerabilities/privilege-escalation/)) precisely because there's no composition-enforced authz floor.
+- 🔧 The pattern for first-party plugins: trust for process safety, **enforce the boundary that matters (authz) by composition** — the host owns the mount and wraps every entry behind auth the plugin can't remove. ADR 0080 §3 is exactly this, and is *stronger* than Backstage (the route-rank fitness gate spans `modules/**/routes/`, so even a forgotten gate is a red build). Deferring true sandboxing is the standard call.
+
+## 5. Thread 4 — Theming, white-labeling & re-skinning
+
+- 📄 **Design tokens** (W3C DTCG format, `$value`/`$type`, first stable 2025.10) are the portable presentation layer ([W3C](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/); [format](https://www.designtokens.org/tr/drafts/format/)); **Style Dictionary** transforms them to CSS vars.
+- 📄 **Headless/unstyled libraries** (Radix, Headless UI, React Aria, shadcn) = logic core + swappable skin. Generalizes: separate behavior/data from presentation so a re-skin is a token swap, not a logic edit.
+- 📄 **Multi-brand / white-label SaaS**: one codebase, brand = config (token set + enabled features), runtime theme injection via CSS custom properties ([multi-brand SaaS](https://medium.com/@kodekx-solutions/<redacted>)).
+
+🔧 Cloud Bongos has the seeds: `branding.json` theme tokens → CSS-var injection at boot (`themeMarkup`), `modules.json` → `window.__MODULES__` section toggles. Gaps: finish the ~90-site brand-string consolidation; unify the duplicated hall/status stylesheets onto one shared token set; keep all logic in the core API so a skin is a thin renderer. ADR 0079 (design-as-code, tools-as-adapters) is the right governance layer.
+
+## 6. Thread 5 — Scoping AI agents to a package (the centerpiece)
+
+- 📄 Bounded, relevant context → higher-quality output, fewer errors, lower token cost ([getbasis.ai](https://www.getbasis.ai/blogs/how-we-made-our-monorepo-ergonomic-for-agents), [tianpan.co](https://co.tianpan.co/blog/<redacted>), [Claude Code best practices](https://code.claude.com/docs/en/best-practices)).
+- 📄 **Package-scoped nested context files** (AGENTS.md / nested CLAUDE.md / .cursor/rules) — [Datadog](https://dev.to/datadog-frontend-dev/<redacted>). Cloud Bongos already does this (nested CLAUDE.md, presence-enforced) — ahead.
+- 📄 **Dependency-graph-scoped context** (`nx affected` / `turbo --filter`; [Nx AI agent skills](https://nx.dev/blog/nx-ai-agent-skills) exposes the project graph to agents).
+- 📄 **Ticket↔component mapping is established**: Jira/Linear "Components", conventional-commit scopes, CODEOWNERS, `nx affected --files`.
+
+🔧 **The synthesis:** `touches[]` is a file-path list (the lowest-altitude form). The industry moves the unit of affinity *up* from files to components/packages. Once modules are first-class, a task should declare **module affinity**; the agent loads only that module + the core API (small context, higher quality), parallel-safety becomes module-disjointness (cleaner than path overlap), and drift detection becomes semantic ("you said dev-box, you touched game"). *(Refined later: see [02](02-module-map.md)/[04](04-module-lifecycle.md) — in a fully modular world the file-path `touches[]` retires entirely in favor of the module label.)*
+
+## 7. Thread 6 — How companies manage AI-assisted dev at scale
+
+- 📄 Anthropic's multi-agent research system: orchestrator-worker, lead decomposes, subagents in parallel each with own context window ([Anthropic](https://www.anthropic.com/engineering/multi-agent-research-system)).
+- 📄 [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code); [Claude Code best practices](https://code.claude.com/docs/en/best-practices); [GitHub Copilot coding agent](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent) (scoped to an issue, isolated env, PR review gate); [Nx AI agent skills](https://nx.dev/blog/nx-ai-agent-skills) (pair affected-graph with AI); [Macroscope](https://macroscope.com/content/ai-code-review-monorepos-complete-guide) (scope AI review to the affected graph).
+
+🔧 Cloud Bongos already implements most of the at-scale playbook (MAS orchestrator-worker, nested context, adversarial grader, per-claim worktrees, claim model). The missing piece is the **<redacted>** step — which module-affinity adds.
+
+## 8. Recommendations (incremental, lightweight-first)
+
+1. Ship ADR 0080 (module manifest + loader + fitness boundary). `[convention + loader]`
+2. **Task→module affinity** as the successor to `touches[]` (the centerpiece). `[convention + loader]`
+3. Use module-affinity to scope agent context. `[convention + loader]`
+4. Finish theming consolidation; unify the UIs' token set; logic stays in the core API. `[convention + loader]`
+5. Per-module nested CLAUDE.md, presence-enforced. `[convention + loader]`
+6. *(optional)* `eslint-plugin-boundaries` if import-graph checks outgrow `fitness.js`. `[convention + loader]`
+7. *(not now)* Workspaces / Nx / Turborepo / Bazel — adds a build step for benefits you don't need as a single-process no-bundler app. `[heavyweight]`
+
+## 9. Bibliography
+
+**Verified primary (✅):** [Nx enforce-module-boundaries](https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries) · [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries) · [Turborepo structuring](https://turborepo.dev/docs/crafting-your-repository/structuring-a-repository) · [Fastify plugins](https://fastify.dev/docs/latest/Reference/Plugins/)
+
+**Primary (📄, verification lost to budget cutoff):** [VS Code extensibility](https://vscode-docs.readthedocs.io/en/stable/extensions/our-approach/) · [Backstage extension points](https://backstage.io/docs/backend-system/architecture/extension-points/) · [Backstage threat model](https://backstage.io/docs/overview/threat-model/) · [W3C Design Tokens 2025.10](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/) · [DTCG format](https://www.designtokens.org/tr/drafts/format/) · [Anthropic multi-agent](https://www.anthropic.com/engineering/multi-agent-research-system) · [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code) · [Claude Code best practices](https://code.claude.com/docs/en/best-practices) · [GitHub Copilot coding agent](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent) · [Nx AI agent skills](https://nx.dev/blog/nx-ai-agent-skills)
+
+**Secondary / blog:** [Datadog AGENTS.md](https://dev.to/datadog-frontend-dev/<redacted>) · [getbasis.ai](https://www.getbasis.ai/blogs/how-we-made-our-monorepo-ergonomic-for-agents) · [tianpan.co](https://co.tianpan.co/blog/<redacted>) · [monorepo.tools/ai](https://monorepo.tools/ai) · [Macroscope](https://macroscope.com/content/ai-code-review-monorepos-complete-guide) · [dependency-cruiser](https://dev.to/jacobandrewsky/<redacted>) · [hexagonal architecture](https://en.wikipedia.org/wiki/<redacted>(software)) · [Patchstack WordPress priv-esc](https://patchstack.com/academy/wordpress/vulnerabilities/privilege-escalation/) · [multi-brand SaaS](https://medium.com/@kodekx-solutions/<redacted>) · [white-label React](https://corecotechnologies.com/development/white-label-react-app/)
+
+*Harness stats: 6 angles · 27 sources · 131 claims extracted · 25 verified (12 confirmed, 13 abstained at the budget cutoff).*