# Artifact map Every file stardust reads or writes, who owns it, what it contains, and how its provenance block is shaped. --- ## Project root (impeccable's format — stardust authors directly) | Path | Format owner | Stardust writes when | Stardust reads when | |------------------|--------------|--------------------------------------------------------------|----------------------------------------| | `PRODUCT.md` | impeccable | `$stardust direct` authors it from the resolved direction | every sub-command (target strategy) | | `DESIGN.md` | impeccable | `$stardust direct` authors it from the resolved direction + brand surface | `prototype`, `migrate` | | `DESIGN.json` | impeccable | `$stardust direct` authors it from the resolved direction + brand surface | `prototype`, `migrate` | | `AGENTS.md` | impeccable | never (read-only for stardust) | every sub-command (Design Context) | Stardust authors `PRODUCT.md`, `DESIGN.md`, and `DESIGN.json` **directly**, treating impeccable's `reference/teach.md` and `reference/document.md` as **format specs** rather than runtime commands. Reasoning: by the time `$stardust direct` runs, the user has already gone through stardust's intent-reasoning interview — re-running impeccable's interview would duplicate questions. The resolved direction in `stardust/direction.md` carries every answer impeccable's interviews would surface. Users who want impeccable to validate or refine the project-root files can run `$impeccable teach` or `$impeccable document` directly at any time; stardust does not own those commands and will not interfere. The same direct-authoring pattern is used for the descriptive files under `stardust/current/` written by `$stardust extract`. ### `DESIGN.json.extensions` The `extensions` object grows with the migrate-template-canon refactor (see `notes/migrate-template-canon-refactor.md`): - **`extensions.canon`** — pinned token values, compositional moves (free-text), and references to `stardust/canon/*` chrome and CSS files (`{ path, sha }` per file). Written by `$stardust prototype --prep` on first approval; extended on subsequent approvals. - **`extensions.modules[]`** — brand module catalog: `id`, `slots` (with `name`, `type`, `required`, optional `default`), `canonicalRendering` reference. Auto-detected during `$stardust extract --prep`; promoted/refined during `$stardust direct --prep`. - **`extensions.colorReservations[]`** — colors reserved to specific modules or contexts (e.g., centennial-red reserved to a `trh-100-lockup` module). Validated at migrate time; violation refuses the page. - **`extensions.metadata`** — site-level metadata defaults: site name, default OG image, theme color, organization JSON-LD, default locale. Composed with per-page metadata at migrate time. --- ## `stardust/` (stardust's territory) ``` stardust/ ├── state.json # state machine (state-machine.md) ├── direction.md # resolved intent + reasoning trace ├── uplift-improvements.md # 5 specific weaknesses — load-bearing for uplift's variant A (written by `stardust:uplift` Phase 2a; absent otherwise) ├── uplift-questions.md # 6–8 "what if…" candidates with disqualifications (written by `stardust:uplift` Phase 2b; absent otherwise) ├── canon/ # design canon (canon-extraction.md) — written by prototype --prep on first approval, extended on subsequent approvals │ ├── header.html # canonical header chrome │ ├── footer.html # canonical footer chrome │ ├── canon.css # compound CSS (button/card/link/form language) │ └── modules/ │ └── .html # canonical rendering per brand module ├── current/ │ ├── PRODUCT.md # impeccable-format strategy of the EXISTING site │ ├── DESIGN.md # impeccable-format visual system of the EXISTING site │ ├── DESIGN.json # sidecar │ ├── brand-review.html # self-contained visual review of the extraction (first eyeball-able artifact) │ ├── _brand-extraction.json # consolidated brand surface (palette, type, motifs, voice, system components) │ ├── _crawl-log.json # discovery + crawl audit trail │ ├── pages/ │ │ └── .json # per-page parsed structure + content (includes metadata block) │ └── assets/ │ ├── logo. # extracted logo │ ├── screenshots/.png # per-page viewport screenshots (used by brand-review) │ └── media/ # extracted images, with original URLs ├── prototypes/ │ ├── -shape.md # per-page compositional brief (page-level deployment record) │ ├── -proposed.html # proposed redesign (iteration target, migration source, user-facing review surface) │ ├── -cinematic.html # cinematic variant — written only when `prototype --cinematic` ran (alongside proposed) │ ├── lenis.min.js # smooth-scroll runtime (copied from skills/prototype/assets/motion/; cinematic only) │ └── lenis.min.css # smooth-scroll styles (cinematic only) └── migrated/ # deployable static HTML site ├── index.html # the home page (slug "home" -> root) ├── _meta.json # sidecar JSON (full reasoning trace) — one per migrated page ├── / │ ├── index.html # one per non-home slug (URL-faithful nesting) │ └── _meta.json ├── docs/api/ # multi-segment slugs nest naturally │ ├── index.html │ └── _meta.json ├── assets/ # self-contained bundle (skills/migrate/reference/asset-bundling.md) │ ├── logo. # copied from current/assets/ │ ├── favicon. # canonical favicon │ ├── favicon-512.png # variants generated during prepare-migration phase 4 │ ├── apple-touch-icon.png │ ├── fonts/ # @font-face files downloaded during prepare-migration phase 4 │ └── # every asset referenced by a migrated page, subdir structure preserved from current/assets/ ├── robots.txt # minimal └── sitemap.xml # derived from migrated inventory ``` The migrated tree is a **self-contained, zip-and-deploy** bundle. Contract in `skills/stardust/reference/migrate-output-format.md`; the `state.json.migrate` block (with `selfContained: true`) is the forward-compat signal downstream consumers test for. ### `stardust/state.json` Owner: every stardust sub-command. Schema in `state-machine.md`. ### `stardust/direction.md` Owner: `$stardust direct`. The full reasoning trace for the resolved direction, written using the format in `skills/direct/reference/direction-format.md`. The agent appends a new section every time direction changes. ### `stardust/current/PRODUCT.md` and `DESIGN.md` Owner: `$stardust extract`. Authored by `$impeccable teach` / `$impeccable document` against the extracted site, but seeded by stardust. These files describe what *is*, not what *should be*. ### `stardust/current/brand-review.html` Owner: `$stardust extract` (Phase 5). Self-contained visual review of the extraction — the **first eyeball-able artifact** the pipeline emits. Renders the canonical brand-board section contract plus a Tensions section that surfaces forced decisions for `direct`. Format spec in `skills/extract/reference/brand-review-template.md`. Embedded CSS only, no external JavaScript, rendered in the brand's own captured colors and fonts. The reviewer is expected to open this file and confirm the extraction captured the site faithfully **before** running `$stardust direct`. Misreads caught here are cheap to fix (re-run extract); misreads caught after `direct` are not. ### `stardust/current/_brand-extraction.json` Owner: `$stardust extract` (Phase 3). Consolidated brand surface — palette, type, motifs, system components, voice, register. Schema in `skills/extract/reference/brand-surface.md`. ### `stardust/current/_crawl-log.json` Owner: `$stardust extract` (Phases 1, 2, 6). Append-only audit trail of discovery and crawl. Re-running extract appends to `runs[]` rather than overwriting. Schema in `skills/extract/reference/ia-extraction.md` § `_crawl-log.json` shape. ### `stardust/current/pages/.json` Owner: `$stardust extract`. Per-page parsed model. Schema lives in `skills/extract/reference/current-state-schema.md` (Phase 1). ### `stardust/current/assets/` Owner: `$stardust extract`. Logo + media extracted from the live site. Filenames preserve the source basename plus a hash to avoid collisions. ### `stardust/prototypes/-shape.md` Owner: `$stardust prototype` (Phase 1). Per-page compositional brief. Carries page-level deployment decisions: section order, layout strategy, key states, interaction model, structural data attributes, unsourced-content list. Format spec in `skills/prototype/reference/page-shape-brief.md`. The brief exists because of the site/page split (see the site-level vs page-level table below). `direct` authors the design **system**; the brief records the **deployment** of that system to a specific page. A direction change invalidates the system; the brief is content-aware-stale only when the system change makes its composition impossible. ### `stardust/prototypes/-proposed.html` Owner: `$stardust prototype`. One file per page — the **proposed redesign on its own**: self-contained, complete HTML page rendered against the target `DESIGN.md`. The user opens it in the browser to review; chat-driven impeccable commands iterate on it; `$stardust migrate` later re-derives from it for the final migrated page. Full contract in `skills/prototype/reference/proposed-file-shell.md`. The file carries a provenance block in `` listing the active direction it was rendered against; when direction changes the page is flagged `stale` in `state.json` and re-runs of `prototype` skip it unless `--all` is passed. ### `stardust/uplift-improvements.md` and `stardust/uplift-questions.md` Owner: `$stardust uplift`. Written in Phase 2 of uplift before any variant renders. **`uplift-improvements.md`** is the load-bearing list of 5 specific captured-site weaknesses that variant A applies exactly. **`uplift-questions.md`** is the 6–8 "what if…" candidate catalog (per `skills/uplift/reference/what-if-candidates.md`) with disqualifications recorded — the audit trail proving that B and C picked their directional bets from the closed catalog rather than improvising. Both files are absent when uplift has not been run; the standard `extract → direct → prototype` chain produces no equivalent artifacts (their content lives implicitly in `direction.md` and the per-page shape briefs). ### `stardust/prototypes/-cinematic.html` Owner: `$stardust prototype --cinematic`. One file per page when the cinematic feature was engaged. Written **alongside** `-proposed.html`, never replacing it — the static prototype remains the load-bearing artifact for accessibility audits, migration consumption, and brand-faithful inheritance reviews. The cinematic file declares an active motion register in its provenance block (`_provenance.motion.register`) and ships the Lenis runtime alongside (relative `