@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/assets/figma-make/guidelines/components.md

@@ -0,0 +1,142 @@
+# AdiaUI — Components
+
+Every primitive is `<name>-ui`. 122 primitives + 4 app shells are
+registered by `everything.min.js`. Reach for a tag before hand-building.
+Full per-component docs + live demos: https://ui-kit.exe.xyz/site/components/<name>
+
+## Picking a component
+
+```
+What are you placing?
+├─ A whole app frame ........... a SHELL (admin / chat / editor / simple)
+├─ A box grouping content ...... <card-ui>  (header / section / footer slots)
+├─ Horizontal/vertical layout .. <row-ui> / <col-ui>  (gap="1".."6")
+├─ A labelled input ............ <field-ui label=""> wrapping the control
+├─ An action ................... <button-ui text="" variant="">
+├─ Tabular data ................ <table-ui>   |  a list ... <list-ui>
+├─ A metric/KPI ................ <stat-ui value="" label="">
+├─ Inline status ............... <badge-ui text=""> | <tag-ui> | <alert-ui>
+├─ Sidebar navigation .......... <nav-ui> + <nav-item-ui icon="" text="">
+└─ Transient/overlay ........... <modal-ui> | <drawer-ui> | <toast-ui> | <tooltip-ui>
+```
+
+## Vocabulary by group
+
+| Group | Tags |
+|---|---|
+| **Layout** | `row-ui` `col-ui` `grid-ui` `page-ui` `card-ui` `pane-ui` `block-ui` `divider-ui` `stack-ui` `section`(slot) |
+| **Text** | `text-ui` `link-ui` `badge-ui` `tag-ui` `icon-ui` `code-ui` `kbd-ui` `mark-ui` `blockquote-ui` `relative-time-ui` `number-format-ui` |
+| **Forms** | `input-ui` `textarea-ui` `select-ui` `combobox-ui` `check-ui` `radio-ui` `switch-ui` `slider-ui` `range-ui` `search-ui` `otp-input-ui` `tags-input-ui` `segmented-ui` `rating-ui` `color-input-ui` `field-ui` `fields-ui` `button-ui` |
+| **Data** | `table-ui` `list-ui` `description-list-ui` `stat-ui` `chart-ui` `heatmap-ui` `timeline-ui` `feed-ui` `pagination-ui` `progress-ui` `progress-row-ui` `step-progress-ui` |
+| **Feedback / overlay** | `alert-ui` `inline-message-ui` `toast-ui` `modal-ui` `drawer-ui` `tooltip-ui` `popover-ui` `empty-state-ui` `skeleton-ui` `spinner-ui` `loading-overlay-ui` |
+| **Navigation** | `nav-ui` `nav-item-ui` `nav-group-ui` `menu-ui` `tabs-ui` `breadcrumb-ui` `command-ui` `context-menu-ui` `toolbar-ui` `segment-ui` `pagination-ui` `toc-ui` `skip-nav-ui` |
+| **Media / misc** | `avatar-ui` `image-ui` `qr-code-ui` `swatch-ui` `swiper-ui` `accordion-ui` `stepper-ui` `tour-ui` `inline-edit-ui` `calendar-picker-ui` `date-range-picker-ui` `datetime-picker-ui` `time-picker-ui` |
+| **Agent surfaces** | `agent-reasoning-ui` `agent-trace-ui` `agent-suggestions-ui` `agent-questions-ui` `agent-feedback-bar-ui` `agent-artifact-ui` `chat-thread-ui` |
+| **Shells** | `admin-shell` `chat-shell` `editor-shell` `simple-shell` (+ their `admin-sidebar` / `admin-topbar` / `admin-page` / … children) |
+
+## Component rules + examples
+
+### `<button-ui>` — label via `text=`
+Two independent attributes:
+- **`variant`** (visual style): `solid` (default) · `outline` · `ghost`. `primary` is an alias of `solid`.
+- **`color`** (semantic intent, composes with variant): `default` · `accent` · `info` · `success` · `warning` · `danger`.
+- **`size`**: `xs` `sm` `md` `lg` `xl`.
+
+```html
+<!-- CORRECT — variant + color compose; size is independent -->
+<button-ui text="Save" variant="primary"></button-ui>
+<button-ui text="Delete" variant="primary" color="danger"></button-ui>   <!-- solid danger -->
+<button-ui text="Cancel" variant="outline"></button-ui>
+<!-- WRONG — label is ignored; renders an empty button -->
+<button-ui variant="primary">Save</button-ui>
+<!-- WRONG — danger is a COLOR, not a variant; this gets no danger styling -->
+<button-ui text="Delete" variant="danger"></button-ui>
+```
+
+### `<card-ui>` — header / section / footer slots
+Body content MUST be inside `<section>`, or it loses inset padding.
+
+```html
+<!-- CORRECT -->
+<card-ui>
+  <header><h3>Plan</h3></header>
+  <section><text-ui>Pro — $29/mo</text-ui></section>
+  <footer><button-ui text="Upgrade" variant="primary"></button-ui></footer>
+</card-ui>
+<!-- WRONG — body bleeds to the edges -->
+<card-ui><text-ui>Pro — $29/mo</text-ui></card-ui>
+```
+
+### `<field-ui>` — label + control + validation row
+Wrap a single control. For 2+ `<radio-ui>`/`<check-ui>`, wrap them in `<col-ui gap="1">` inside the field, or they overlap.
+
+```html
+<field-ui label="Email"><input-ui type="email" required></input-ui></field-ui>
+<field-ui label="Plan">
+  <col-ui gap="1">
+    <radio-ui name="plan" label="Free"></radio-ui>
+    <radio-ui name="plan" label="Pro"></radio-ui>
+  </col-ui>
+</field-ui>
+```
+
+### `<nav-ui>` — sidebar navigation (NOT `<menu-ui>`)
+```html
+<nav-ui>
+  <nav-item-ui icon="house" text="Home" selected></nav-item-ui>
+  <nav-item-ui icon="gear" text="Settings"></nav-item-ui>
+</nav-ui>
+```
+`<menu-ui>` is only for popover/dropdown action menus.
+
+### `<stat-ui>` — metric/KPI
+```html
+<stat-ui value="$12.4k" label="Revenue" trend="up" change="+8%"></stat-ui>
+```
+
+### `<table-ui>` — never author `<tr>`/`<td>` by hand
+The HTML parser strips table tags inside custom elements. Provide columns + data via attributes/JSON or `<col-def>`; don't write raw `<thead>/<tbody>/<tr>`.
+
+### `<modal-ui>` / `<drawer-ui>` — `[text]` + `slot="footer"`
+`<modal-ui>` titles via a `[text]`/heading attr and footer via `slot="footer"` — it does NOT use card-ui's header/section/footer. Check the live demo before authoring.
+
+## App shell skeleton
+
+```html
+<admin-shell mode="rounded borderless">
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header"><span slot="heading">My App</span></admin-topbar>
+    <section>
+      <nav-ui>
+        <nav-item-ui icon="house" text="Home" selected></nav-item-ui>
+        <nav-item-ui icon="chart-bar" text="Reports"></nav-item-ui>
+      </nav-ui>
+    </section>
+  </admin-sidebar>
+  <admin-content>
+    <admin-topbar><breadcrumb-ui><span>Dashboard</span></breadcrumb-ui></admin-topbar>
+    <admin-scroll>
+      <admin-page>
+        <admin-page-header>
+          <header>
+            <div>
+              <h1>Dashboard</h1>
+              <div data-actions><button-ui text="Share" variant="outline" size="sm"></button-ui></div>
+            </div>
+            <p>Welcome back.</p>
+          </header>
+        </admin-page-header>
+        <admin-page-body>
+          <row-ui gap="3">
+            <card-ui><section><stat-ui value="$12.4k" label="Revenue"></stat-ui></section></card-ui>
+            <card-ui><section><stat-ui value="1,204" label="Users"></stat-ui></section></card-ui>
+          </row-ui>
+        </admin-page-body>
+      </admin-page>
+    </admin-scroll>
+  </admin-content>
+</admin-shell>
+```
+
+Icon names (`icon="…"` / `<icon-ui name="…">`) are Phosphor names:
+`house` `gear` `magnifying-glass` `plus` `trash` `chart-bar` `bell` `user`.

package/skills/adia-ui-kit/assets/figma-make/guidelines/styles.md

@@ -0,0 +1,118 @@
+# AdiaUI — Styles
+
+## Load the rollup CSS (one file, not 119)
+
+AdiaUI's CSS is a single pre-flattened rollup. Load it once — never
+import individual component stylesheets in Figma Make.
+
+```html
+<!-- CDN (simplest — recommended for Make) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.css">
+```
+
+```js
+// OR, if the npm package is installed in the kit:
+import '@adia-ai/web-components/css/bundled';   // the rollup — every primitive
+```
+
+Add a shell's CSS only for the shell tier you render:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.css">
+<!-- swap shell/admin-shell for chat/chat-shell · editor/editor-shell · simple/simple-shell -->
+```
+
+**Do not** restyle AdiaUI internals with Tailwind or utility classes.
+Components are styled with CSS `@scope` and design tokens; utility classes
+on the host won't reach the internals and will fight the cascade. Change
+appearance through **attributes** (`variant`, `size`, `gap`) and
+**`--a-*` tokens** (see `tokens.md`).
+
+## Theming — two independent axes
+
+Set both on a wrapper element (or `<html>`). They are separate attributes:
+
+| Attribute | Controls | Values |
+|---|---|---|
+| `theme` | Named color palette | `default` `ocean` `forest` `sunset` `midnight` `lavender` `rose` `slate` |
+| `data-scheme` | Light/dark mode | `light` `dark` `system` |
+
+```html
+<!-- Ocean palette, follow the OS for light/dark -->
+<html theme="ocean" data-scheme="system">
+```
+
+```
+Choosing:
+├─ Want a brand color set? ........... theme="ocean" (or forest/sunset/…)
+├─ Want light or dark? ............... data-scheme="light" | "dark"
+└─ Want to follow the user's OS? ..... data-scheme="system"  (default behavior)
+```
+
+Omitting `theme` uses `default`. Omitting `data-scheme` follows the
+OS preference. Both cascade — set them once high in the tree.
+
+## Layout — use the layout primitives, not fl/grid utility CSS
+
+| Need | Use | Notes |
+|---|---|---|
+| Row of items | `<row-ui gap="3">` | horizontal flex; `gap` = token step 1–6 |
+| Column of items | `<col-ui gap="2">` | vertical flex |
+| Grid | `<grid-ui>` | responsive grid |
+| Page wrapper | `<page-ui>` | max-width + page inset |
+| Overlapping layers | `<stack-ui>` | **z-axis** (badge over avatar) — NOT vertical |
+| Spacer / divider | `<divider-ui>` | |
+
+`gap` (and most spacing attrs) take a **token step 1–6**, not pixels —
+they scale with density (see `tokens.md`). `gap="3"` ≈ 12px at default
+density.
+
+```html
+<!-- CORRECT — vertical stack of three cards -->
+<col-ui gap="3">
+  <card-ui><section>…</section></card-ui>
+  <card-ui><section>…</section></card-ui>
+</col-ui>
+<!-- WRONG — stack-ui overlaps them in one cell -->
+<stack-ui><card-ui>…</card-ui><card-ui>…</card-ui></stack-ui>
+```
+
+### Structural layout is the one inline-style exception
+
+The "use attributes, not inline CSS" rule targets things a primitive or
+attribute *already covers* — `gap`, spacing, alignment, sizing, color.
+**Page-frame scaffolding has no primitive, so inline structural CSS is
+fine there:** a full-height app frame, fixed-width sidebars, scroll
+panes, and custom CSS grids.
+
+```html
+<!-- OK — structural; no primitive expresses a full-height chat frame -->
+<article style="display:flex; height:100vh;">
+  <aside style="width:240px; overflow:auto; border-right:1px solid var(--a-border-subtle);">…</aside>
+  <section style="flex:1; overflow:auto;">…use row-ui/col-ui/card-ui INSIDE…</section>
+</article>
+```
+
+The test: **does a primitive or attribute already do this?**
+- Yes (`gap`, `size`, `variant`, `color`, row/col/grid/stack) → use it, never inline.
+- No (`height:100vh`, `flex:1` scroll pane, `grid-template-columns:1fr auto 1fr`) → inline structural CSS is acceptable; still use tokens (`var(--a-*)`), not raw px/hex, and put the *content* inside primitives.
+
+Keep structural inline CSS on the **frame** only — never reach for it to
+restyle a component that has an attribute for the job.
+
+## Typography
+
+Use the heading tags + `<text-ui>`; the rollup CSS styles them. Prose
+scale tokens (`--a-display`, `--a-title`, `--a-body`, `--a-caption`)
+back the sizes. Don't set raw `font-size` — use the semantic element
+(`<h1>`–`<h6>`, `<text-ui>`) or the size token.
+
+```html
+<header align="center" size="lg">
+  <col-ui>
+    <text-ui kicker>PRICING</text-ui>
+    <h1>Simple, transparent pricing</h1>
+    <text-ui deck>Pick a plan that scales with you.</text-ui>
+  </col-ui>
+</header>
+```

package/skills/adia-ui-kit/assets/figma-make/guidelines/tokens.md

@@ -0,0 +1,120 @@
+# AdiaUI — Design Tokens
+
+All design tokens are CSS custom properties prefixed **`--a-*`**, defined
+in the rollup CSS. Restyle through these — never hard-coded colors,
+pixels, or utility classes.
+
+## Philosophy
+
+The system is **parametric**: a handful of root knobs drive entire scales
+via `calc()`. Change a knob at a provider boundary (a wrapper element) and
+every spacing/radius/color downstream re-derives. You rarely set a leaf
+token — you set the knob.
+
+```
+Want to change…
+├─ overall spacing tightness ... set --a-density   (number; 1 = default)
+├─ corner roundness ............ set --a-radius-k   (radius multiplier)
+├─ the brand palette ........... theme="ocean" (see styles.md)
+├─ light/dark .................. data-scheme="dark" (see styles.md)
+└─ one component's color ....... override its --<component>-* token (below)
+```
+
+## Token families
+
+| Family | Tokens (examples) | Purpose |
+|---|---|---|
+| **Spacing** | `--a-space-1` … `--a-space-12` (+ `-0-5`, `-1-5`) | Padding / margins; `--a-space-1` = 4px at density 1 |
+| **Gap** | `--a-gap-1` … `--a-gap-6` | Flex/grid gaps (what `gap="n"` maps to) |
+| **Radius** | `--a-radius-sm` `--a-radius-md` `--a-radius-lg` | Corner rounding |
+| **Size** | `--a-size-*` | Control heights (button/input/etc.) |
+| **Shadow** | `--a-shadow-sm` `--a-shadow-md` `--a-shadow-lg` | Elevation |
+| **Inset** | `--a-inset-*` | Component interior padding |
+| **Type scale** | `--a-display` `--a-title` `--a-section` `--a-body` `--a-caption` `--a-kicker` | Prose sizes |
+| **Density knob** | `--a-density` | Multiplies ALL spatial dimensions |
+
+## Semantic color roles
+
+Use **role** tokens, not raw colors. Roles resolve correctly under every
+`theme` + `data-scheme` combination.
+
+| Token | Use for |
+|---|---|
+| `--a-fg` | Default text/foreground |
+| `--a-fg-strong` | High-emphasis text |
+| `--a-fg-subtle` | Muted / secondary text |
+| `--a-bg` | Default background |
+| `--a-border` / `--a-border-subtle` | Borders / dividers |
+| `--a-primary` | Primary-action fill (what `<button-ui variant="primary">` uses) |
+| `--a-accent-bg` / `--a-accent-muted` / `--a-accent-strong` | Accent fills |
+| `--a-success-* / --a-warning-* / --a-danger-* / --a-info-*` | Status colors |
+| `--a-chrome-light` | Text/dots ON a filled primary/accent disc (NOT `--a-accent-fg`, which resolves near-black) |
+
+**Never** use `--a-bg` as a foreground or `--a-fg` as a background. For a
+primary fill use `--a-primary` with `--a-chrome-light` text, not raw hex.
+
+```css
+/* CORRECT — semantic roles */
+.note { color: var(--a-fg-subtle); background: var(--a-bg); border: 1px solid var(--a-border); }
+/* WRONG — raw colors fight the theme + break dark mode */
+.note { color: #6b7280; background: #ffffff; border: 1px solid #e5e7eb; }
+```
+
+## Restyle via attributes first
+
+Most appearance changes have a first-class **attribute** — reach for it
+before any token. Do not set component tokens inline with `style="…"`;
+inline overrides bloat the markup and bypass the documented API.
+
+```html
+<!-- CORRECT — the attribute API expresses intent -->
+<button-ui text="Buy" variant="primary"></button-ui>
+<button-ui text="Delete" variant="primary" color="danger"></button-ui>
+<!-- WRONG — inline token override where an attribute exists -->
+<button-ui text="Buy" style="--button-bg: var(--a-primary);"></button-ui>
+```
+
+The common attributes: `variant` (visual style), `color` (semantic
+intent), `size` (`xs`–`xl`), `gap` (`1`–`6`). See `components.md`.
+
+## Overriding a component (only when there's no attribute)
+
+For a property with no attribute — e.g. tinting every card in one region —
+override the component's named token in a **scoped CSS rule on an
+ancestor**, never inline per-instance. The pattern is `--<component>-<prop>`:
+
+```css
+/* Tint + round every card inside .promo — one rule, region-scoped */
+.promo {
+  --card-bg: var(--a-accent-muted);
+  --card-radius: var(--a-radius-lg);
+}
+```
+
+## Density (the highest-leverage knob)
+
+`--a-density` scales every spacing/padding/gap token at once. Set it in a
+scoped CSS rule on a region wrapper — a denser table area, a roomier
+marketing section:
+
+```css
+.dense-region { --a-density: 0.85; }   /* 15% tighter everywhere inside */
+```
+
+Default is `1`. Lower = tighter, higher = roomier. Because spacing is
+parametric, this stays internally consistent — you don't restyle each
+component.
+
+## Rules
+
+1. **Prefer attributes** (`variant` / `color` / `size` / `gap`) over token
+   overrides. Reach for a token only when no attribute covers the change.
+2. **Never set tokens inline with `style="…"`.** Token overrides go in a
+   scoped CSS rule on an ancestor, never per-instance inline.
+3. No raw hex/rgb colors — use semantic role tokens.
+4. No pixel spacing — use `--a-space-*` / `--a-gap-*` or the `gap="n"`
+   attribute (token step 1–6).
+5. Restyle a component via its `--<component>-*` token, not by targeting
+   its internal elements.
+6. Change scale globally via `--a-density` / `--a-radius-k`, not by
+   editing each token.

package/skills/adia-ui-kit/assets/team-scaffold/archive-README.md

@@ -0,0 +1,30 @@
+# `archive/` — Superseded registries, historical legacy docs
+
+Immutable after write. Use this folder when:
+
+- Migrating the ticket-system layout (e.g. moving from `docs/outbound/`
+  to `.agents/team/tickets/` — the historical registry is archived here,
+  not deleted).
+- Pruning a stale arc of tickets that's been fully resolved and is no
+  longer relevant to active work.
+
+## What does NOT go here
+
+- **Retracted tickets** — those go BACK to `../drafts/` with
+  `status: retracted`. Retraction is a status change, not archival.
+- **Resolved tickets** — those stay in `../outbox/` with
+  `status: resolved`. Resolution is also a status change.
+- **Working drafts** — stay in `../drafts/` until promoted or pruned.
+
+## Adding an archive entry
+
+When archiving a registry or batch of tickets:
+
+1. Add a one-line note to `../REGISTRY.md` pointing at the new archived
+   location (with the date of the move).
+2. Move the file(s) into `archive/`.
+3. Do not edit archived files post-move. If a fact in an archived file
+   is wrong, draft a new ticket explaining the correction — don't
+   rewrite history.
+
+Archived files are part of the audit trail forever.

package/skills/adia-ui-kit/assets/team-scaffold/drafts-README.md

@@ -0,0 +1,57 @@
+# `drafts/` — Pre-publication rough drafts
+
+Agent rough drafts and coordinator work-in-progress live here. Drafts
+accumulate until a human (or human-driven agent) runs
+`ticket-tool finalize <NN>`, which moves them to `../outbox/`.
+
+## Naming
+
+`FEEDBACK-NN--<recipient>--YYYY-MM-DD.md` — same naming as the eventual
+outbox file. The folder it sits in IS the state marker; no `.draft`
+suffix is needed. Frontmatter `status: draft` reinforces.
+
+For RESPONSE drafts (self-review or in-progress placeholders before
+upstream sends the real RESPONSE): `RESPONSE-NN--<sender>--YYYY-MM-DD.md`.
+
+## Frontmatter contract
+
+See `../README.md` §Draft Frontmatter Contract. In short:
+
+```yaml
+---
+id: "NN"                  # from `ticket-tool next-id`
+type: feedback
+recipient: adia-ui
+date: "YYYY-MM-DD"
+author: "<agent> (<session-context>)"
+project: "<consumer-project>"
+status: draft
+references: []
+version: "@adia-ai/web-components@X.Y.Z"
+priority: p0|p1|p2|p3
+---
+```
+
+## When agents draft here
+
+The `adia-ui-kit` skill §AutoCapture rule binds the agent: whenever it
+observes a bug / gap / friction / stale pattern in `@adia-ai/*` during
+ANY session, draft a ticket here as a side-effect of the work that
+surfaced it. Do not block; do not ask permission; do not wait. Surface
+the draft in the session summary so the user knows it's pending review.
+
+## Retracted tickets
+
+When a finalized FEEDBACK in `../outbox/` is dismissed correctly by an
+upstream RESPONSE (or self-review reveals it was wrong), it moves BACK
+here via `ticket-tool retract <NN>`. Status flips to `retracted` and a
+`retracted-reason:` front-matter field is populated. The file stays in
+the audit trail forever — drafts/ is its final resting place, but the
+REGISTRY.md row stays with status `retracted`.
+
+## Pruning
+
+Drafts that the human declines to ship (and aren't formal retractions)
+can be deleted outright. If the discard is policy-relevant ("we decided
+this is consumer-side, not framework"), capture the reason in
+`../../notes/<date>-discard-<slug>.md` before deleting.

package/skills/adia-ui-kit/assets/team-scaffold/inbox-README.md

@@ -0,0 +1,76 @@
+# `inbox/` — RESPONSE tickets received from upstream
+
+When upstream maintainers reply to a FEEDBACK we filed, file their
+response here. Each RESPONSE pairs 1:1 with a FEEDBACK in `../outbox/`
+(or N:1 in the case of followups).
+
+## Naming
+
+`RESPONSE-NN--<sender>--YYYY-MM-DD.md`, where `NN` matches the FEEDBACK
+this responds to.
+
+For multi-round responses: `RESPONSE-NN--<sender>--YYYY-MM-DD--followup.md`.
+
+## Frontmatter contract
+
+```yaml
+---
+id: "NN"
+type: response
+recipient: <consumer-project>           # us — who the response is to
+date: "YYYY-MM-DD"
+author: "<upstream-maintainer-name>"
+project: "<upstream-project-name>"
+references:
+  - "FEEDBACK-NN--<recipient>--YYYY-MM-DD"
+version: "@adia-ai/web-components@X.Y.Z"
+status: submitted | resolved
+---
+```
+
+## Body discipline — verdict per claim
+
+`references/response-authoring.md` in the `adia-ui-kit` skill is the
+canonical procedural detail. In short, each claim from the original
+FEEDBACK gets exactly one verdict marker:
+
+| Marker | Verdict                       |
+| ------ | ----------------------------- |
+| ✅     | Confirmed (shipped / accepting) |
+| ⚠️     | Confirmed — partial           |
+| ⏳     | Deferred                      |
+| ❌     | Dismissed (not-reproducible / by-design / incorrect-claim) |
+| 🔍    | Needs clarification           |
+| 🔀    | Out of scope — redirected     |
+
+Verdicts MUST cite a runtime line (`components/<name>/<file>.js:LINE`)
+to substantiate. Verdicts without anchors are opinion, not response.
+
+## Registering an incoming response
+
+```bash
+python3 scripts/ticket-tool.py register-response <NN>
+```
+
+That tool:
+
+1. Adds a row to the RESPONSE table in `../REGISTRY.md`.
+2. Flips the matching FEEDBACK row's status: `submitted` → `responded`.
+3. Reports any verdict-class observations (e.g. "1 dismissed → consider
+   retracting FEEDBACK-NN" or "2 partial → consider drafting a followup").
+
+## Triage after registering
+
+Read the response end-to-end. If any verdicts are:
+
+- **❌ Dismissed (incorrect-claim)** — consider retracting your FEEDBACK
+  via `ticket-tool retract <NN> --reason "<verdict citation>"`. The file
+  moves back to `drafts/` with `status: retracted`.
+- **⚠️ Partial** or **🔍 Needs clarification** — draft a followup via
+  `ticket-tool new feedback <recipient> --followup-of <NN>`. Address
+  the partial / answer the clarification.
+- **⏳ Deferred** — capture the cut horizon in your project notes; no
+  action required on the ticket itself.
+- **✅ Confirmed** — once the fix actually ships in a release, update
+  the FEEDBACK status to `resolved` via `ticket-tool set-status <NN> resolved`
+  and cite the commit SHA + version in the `shipped:` front-matter field.

package/skills/adia-ui-kit/assets/team-scaffold/outbox-README.md

@@ -0,0 +1,46 @@
+# `outbox/` — Polished FEEDBACK + REQUEST tickets
+
+Submitted (or ready-to-submit) tickets live here. Promoted from
+`../drafts/` via `ticket-tool finalize <NN>`. Once here, the body should
+not be edited — corrections go in a sibling `--followup.md` file that
+cross-references the original.
+
+## Naming
+
+| Pattern                                                  | When used |
+| -------------------------------------------------------- | --------- |
+| `FEEDBACK-NN--<recipient>--YYYY-MM-DD.md`                | Initial filing |
+| `FEEDBACK-NN--<recipient>--YYYY-MM-DD--followup.md`      | Addendum after a RESPONSE |
+| `FEEDBACK-NN--OMISSIONS-DEFENSE.md`                      | Companion file when the exclusion list has 15+ items or 4+ rationale categories |
+
+## Frontmatter status progression
+
+```
+status: draft        ← in drafts/
+status: submitted    ← when ticket-tool finalize promoted it (in outbox/)
+status: responded    ← when ticket-tool register-response noted an inbox/ RESPONSE
+status: resolved     ← when the response triage closed the loop
+status: retracted    ← if the ticket was wrong; file moves back to drafts/
+```
+
+Status edits to existing rows in `../REGISTRY.md` are corrections, not
+rewrites. Use `ticket-tool set-status <NN> <status>` to keep the registry
+in sync.
+
+## Submitting upstream
+
+The tooling stops at "in `outbox/`, registered, committed." Opening the
+GitHub issue / sending the email / posting to Slack is out of scope —
+do that step manually using the polished file as the message body.
+
+## Once acted on by upstream
+
+When upstream replies, file the response in `../inbox/RESPONSE-NN-…`
+and run `ticket-tool register-response <NN>`. That tool:
+
+1. Adds a row to the RESPONSE table in `../REGISTRY.md`.
+2. Flips the FEEDBACK row's status from `submitted` → `responded`.
+3. Cross-links the two artifacts via the `references:` front-matter.
+
+If the response triggers a followup, draft it with
+`ticket-tool new feedback <recipient> --followup-of <NN>`.

package/skills/adia-ui-kit/assets/team-scaffold/team-root.README.md

@@ -0,0 +1,51 @@
+# Team Workspace (`.agents/team/`)
+
+**Shared team artifacts authored by AI agents across harnesses** —
+companion to `.agents/skills/` (procedural knowledge), `.agents/prompts/`
+(prompt templates), and `.agents/routines/` (scheduled remote-agent
+prompts). Where those folders hold *how* agents work, this folder holds
+*what* agents produce on behalf of the team.
+
+## Tree
+
+```
+.agents/team/
+└── tickets/
+    ├── REGISTRY.md            — master append-only index of every FEEDBACK + RESPONSE
+    ├── README.md              — ticket lifecycle specification (drafts ⇄ outbox ⇄ inbox)
+    ├── drafts/                — agent rough drafts, blocker notes; pre-publication
+    ├── outbox/                — polished FEEDBACK-NN tickets sent upstream
+    ├── inbox/                 — RESPONSE-NN tickets received from upstream
+    └── archive/               — superseded registries, historical legacy docs
+```
+
+## Philosophy
+
+- **Harness-agnostic** — Claude Code, Hermes, Cursor, Codex all write
+  here. No tool-specific subfolders.
+- **Append-only registry** — `REGISTRY.md` is the audit trail. Edits
+  to existing rows are corrections, not rewrites.
+- **Defensible by default** — every ticket follows the 4-block-per-finding
+  discipline (`What happened / Root cause / Reproduction / Request`)
+  with verified exclusions and cost estimates. The `adia-ui-kit` skill
+  §FeedbackDiscipline section defines the principles; `references/feedback-authoring.md`
+  in that skill is the full procedural detail (vendored from
+  `/Users/kimba/Projects/adia/color-app/.agents/team/skills/`, where
+  the discipline was forged through 60+ real tickets).
+- **Four-stage pipeline** — drafts (work-in-progress) → outbox
+  (submitted) → inbox (response received) → archive (superseded only).
+  Retracted tickets move BACK to drafts/ with `status: retracted` —
+  they're not deleted, the registry row stays.
+
+## Ownership
+
+- **Agents** — draft to `tickets/drafts/`, never write directly to
+  `outbox/` or `inbox/`.
+- **Humans (or human-driven agents)** — finalize drafts to `outbox/`
+  via the gated promote tool. File RESPONSE-NN to `inbox/` when
+  upstream replies. Maintain `REGISTRY.md`.
+
+See `tickets/README.md` (at the destination) or `../tickets-README.md`
+(this asset's sibling) for the workflow + format specifications; see the
+`adia-ui-kit` skill in `.agents/skills/` for the authoring discipline and
+tooling.