@hybridlabor-api/aos 4.13.2 → 4.14.1

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/architecture/meta.json

@@ -0,0 +1 @@
+{"id":"architecture","label":"Architecture","description":"A system design with diagram, data model, endpoints, trade-off decision and implementation map.","useWhen":"You are designing or reshaping a service or system and need the structure, interfaces and trade-offs agreed before building.","hasBoard":false}

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/architecture/plan.mdx

@@ -0,0 +1,195 @@
+---
+title: Parcelly - Delivery Tracking Service
+status: draft
+needs-store: foundations
+needs-ingest: store
+needs-api: store
+needs-notify: ingest
+needs-launch: api, notify
+---
+
+# Parcelly: Delivery Tracking Service
+
+<Callout tone="note" title="How to use this template">
+
+Replace the Parcelly example with your system: rewrite the goals and constraints, redraw the diagram, edit the data model and endpoints, and record your real trade-off in the Decision. Keep the implementation map aligned with the build order. All names here are invented.
+
+</Callout>
+
+## Goal and constraints
+
+Parcelly is a fictional service that tracks parcels for small online shops. Carriers push scan events, shops and customers read the current status.
+
+- Show the latest status within 10 seconds of a carrier scan.
+- Handle 300 events per second at peak, 20 million parcels stored.
+- Keep a full event history for 12 months.
+
+<Table title="Constraints" columns={["Constraint", "Value"]} rows={[
+  ["Team", "Three engineers, no dedicated ops"],
+  ["Budget", "Managed services only, under 1,500 per month"],
+  ["Availability", "99.9 percent for reads, writes may queue"],
+  ["Compliance", "Customer addresses deleted 90 days after delivery"],
+]} />
+
+## System overview
+
+<Mermaid label="Components" source={"flowchart LR\n  C[Carrier webhooks] --> G[Ingest gateway]\n  G --> Q[(Event queue)]\n  Q --> W[Event worker]\n  W --> D[(Parcel database)]\n  W --> N[Notifier]\n  N --> E[Email and SMS provider]\n  D --> A[Read API]\n  A --> S[Shop dashboard]\n  A --> T[Customer tracking page]"} />
+
+## Data model
+
+<DataModel entities={[
+  { name: "parcel", fields: [
+    { name: "id", type: "uuid", note: "Primary key" },
+    { name: "shop_id", type: "uuid", note: "Owner shop" },
+    { name: "carrier_ref", type: "text", note: "Unique per carrier" },
+    { name: "status", type: "enum", note: "created, in_transit, out_for_delivery, delivered, failed" },
+    { name: "updated_at", type: "timestamptz" },
+  ] },
+  { name: "parcel_event", fields: [
+    { name: "id", type: "uuid" },
+    { name: "parcel_id", type: "uuid", note: "References parcel" },
+    { name: "kind", type: "text", note: "Carrier scan code" },
+    { name: "occurred_at", type: "timestamptz", note: "Carrier time, not receive time" },
+    { name: "payload", type: "jsonb", note: "Raw event, kept 12 months" },
+  ] },
+]} />
+
+## Endpoints
+
+<Endpoint method="POST" path="/v1/carriers/{carrier}/events" params={[
+  { name: "carrier", in: "path", type: "string", description: "Carrier slug" },
+  { name: "X-Signature", in: "header", type: "string", description: "HMAC of the body" },
+]} examples={[
+  { label: "202 Accepted", code: "{ \"accepted\": 3 }" },
+]}>
+
+Accepts a batch of scan events. Verifies the signature, writes to the queue and returns without waiting for processing.
+
+</Endpoint>
+
+<Endpoint method="GET" path="/v1/parcels/{id}" params={[
+  { name: "id", in: "path", type: "uuid", description: "Parcel id" },
+]} examples={[
+  { label: "200 OK", code: "{ \"id\": \"b1f0\", \"status\": \"out_for_delivery\", \"events\": [] }" },
+]}>
+
+Returns the current status and the event history, newest first.
+
+</Endpoint>
+
+## Decision
+
+<Decision title="How do events reach the database?" question="Which delivery path do we use between the gateway and the parcel database?" options={[
+  { id: "queue", label: "Managed queue and worker", detail: "Absorbs carrier bursts, retries on failure, one more moving part.", recommended: true },
+  { id: "direct", label: "Gateway writes to the database directly", detail: "Fewest parts, but bursts hit the database and carrier retries duplicate rows." },
+  { id: "stream", label: "Event streaming platform", detail: "Strong replay, too heavy for three engineers." },
+]}>
+
+Carriers retry aggressively when we answer slowly. A queue lets the gateway answer in milliseconds and the worker deduplicate by carrier reference and event time.
+
+</Decision>
+
+## Trade-offs
+
+<Table title="What we accept" columns={["Choice", "Gain", "Cost"]} rows={[
+  ["Queue between gateway and database", "Burst tolerance, retries", "Status can lag by a few seconds"],
+  ["Relational store with jsonb payload", "Simple queries, one system", "Payload size grows, needs the 12 month purge"],
+  ["Managed notification provider", "No deliverability work", "Per-message cost"],
+]} />
+
+## Build map
+
+### Foundations {#foundations}
+
+Accounts, environments and CI.
+
+<Checklist title="Foundations tasks" items={[
+  { label: "Staging and production environments", checked: true },
+  { label: "CI with migration check" },
+]} />
+
+<ImplementationMap files={[
+  { path: "infra/environments.tf", change: "added", note: "Staging and production" },
+  { path: ".github/workflows/ci.yml", change: "added", note: "Test and migration dry run" },
+]} />
+
+### Parcel store {#store}
+
+Schema, retention and purge.
+
+<Checklist title="Store tasks" items={[
+  { label: "Tables parcel and parcel_event with indexes" },
+  { label: "Nightly purge: payload after 12 months, addresses after 90 days" },
+]} />
+
+<ImplementationMap files={[
+  { path: "db/migrations/001_parcels.sql", change: "added", note: "parcel and parcel_event tables" },
+  { path: "jobs/purge.ts", change: "added", note: "Retention purge" },
+]} />
+
+### Ingest {#ingest}
+
+Gateway and worker.
+
+<Checklist title="Ingest tasks" items={[
+  { label: "Signature check per carrier" },
+  { label: "Worker with dedupe by carrier_ref and occurred_at" },
+  { label: "Dead letter queue and alert" },
+]} />
+
+<ImplementationMap files={[
+  { path: "services/gateway/events.ts", change: "added", note: "Verify, enqueue, answer 202" },
+  { path: "services/worker/process-event.ts", change: "added", note: "Dedupe, update status" },
+]} />
+
+### Read API {#api}
+
+Status and history reads.
+
+<Checklist title="API tasks" items={[
+  { label: "GET /v1/parcels/{id} with cache of 5 seconds" },
+  { label: "Shop-scoped listing with cursor paging" },
+]} />
+
+<ImplementationMap files={[
+  { path: "services/api/parcels.ts", change: "added", note: "Read handlers" },
+]} />
+
+### Notifications {#notify}
+
+Email and SMS on status change.
+
+<Checklist title="Notify tasks" items={[
+  { label: "Notify on out_for_delivery and delivered" },
+  { label: "Per-shop opt out" },
+]} />
+
+<ImplementationMap files={[
+  { path: "services/worker/notify.ts", change: "added", note: "Template and provider call" },
+]} />
+
+### Launch {#launch}
+
+<Checklist title="Launch tasks" items={[
+  { label: "Load test at 600 events per second" },
+  { label: "Onboard three pilot shops" },
+]} />
+
+<AgentTrail />
+
+## Risks
+
+<Table title="Risks" columns={["Risk", "Likelihood", "Mitigation"]} rows={[
+  ["Carrier sends events out of order", "High", "Order by occurred_at, never by receive time"],
+  ["Queue outage stops status updates", "Low", "Gateway buffers to disk for 10 minutes, alert on queue age"],
+  ["Provider rate limits notifications", "Medium", "Batch and back off, drop to email only"],
+]} />
+
+## Open questions
+
+<QuestionForm title="Open Questions" questions={[
+  { title: "Do we offer a public tracking page without login?", mode: "single", options: [
+    { label: "Yes, with an unguessable id", recommended: true }, { label: "No, login only" } ] },
+  { title: "Retention for event payloads?", mode: "single", options: [
+    { label: "12 months", recommended: true }, { label: "6 months" }, { label: "24 months" } ] },
+]} />

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/architecture/standard.md

@@ -0,0 +1,95 @@
+# Parcelly: Delivery Tracking Service
+
+> **How to use this template:** replace the Parcelly example with your system. Rewrite goals, diagram, data model, endpoints and the trade-off decision. All names here are invented.
+
+**Status:** draft
+
+## 1. Goal and constraints
+
+Parcelly is a fictional service that tracks parcels for small online shops. Carriers push scan events, shops and customers read the current status.
+
+- Show the latest status within 10 seconds of a carrier scan.
+- Handle 300 events per second at peak, 20 million parcels stored.
+- Keep a full event history for 12 months.
+
+| Constraint | Value |
+|------------|-------|
+| Team | Three engineers, no dedicated ops |
+| Budget | Managed services only, under 1,500 per month |
+| Availability | 99.9 percent for reads, writes may queue |
+| Compliance | Customer addresses deleted 90 days after delivery |
+
+## 2. System overview
+
+```mermaid
+flowchart LR
+  C[Carrier webhooks] --> G[Ingest gateway]
+  G --> Q[(Event queue)]
+  Q --> W[Event worker]
+  W --> D[(Parcel database)]
+  W --> N[Notifier]
+  N --> E[Email and SMS provider]
+  D --> A[Read API]
+  A --> S[Shop dashboard]
+  A --> T[Customer tracking page]
+```
+
+## 3. Data model
+
+| Entity | Field | Type | Note |
+|--------|-------|------|------|
+| parcel | id | uuid | Primary key |
+| parcel | shop_id | uuid | Owner shop |
+| parcel | carrier_ref | text | Unique per carrier |
+| parcel | status | enum | created, in_transit, out_for_delivery, delivered, failed |
+| parcel | updated_at | timestamptz | |
+| parcel_event | id | uuid | |
+| parcel_event | parcel_id | uuid | References parcel |
+| parcel_event | kind | text | Carrier scan code |
+| parcel_event | occurred_at | timestamptz | Carrier time, not receive time |
+| parcel_event | payload | jsonb | Raw event, kept 12 months |
+
+## 4. Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | `/v1/carriers/{carrier}/events` | Accept a batch of scan events, verify HMAC in `X-Signature`, enqueue, answer 202 |
+| GET | `/v1/parcels/{id}` | Current status and event history, newest first |
+
+## 5. Decision
+
+| Question | Options | Recommendation | Why |
+|----------|---------|----------------|-----|
+| How do events reach the database? | Managed queue and worker / direct write / streaming platform | **Managed queue and worker** | Carriers retry when we answer slowly; the queue lets the gateway answer in milliseconds and the worker deduplicate |
+
+**Trade-offs accepted**
+
+| Choice | Gain | Cost |
+|--------|------|------|
+| Queue between gateway and database | Burst tolerance, retries | Status can lag by a few seconds |
+| Relational store with jsonb payload | Simple queries, one system | Payload grows, needs the 12 month purge |
+| Managed notification provider | No deliverability work | Per-message cost |
+
+## 6. Build order
+
+- [x] Staging and production environments
+- [ ] CI with migration check
+- [ ] Tables parcel and parcel_event with indexes
+- [ ] Nightly purge: payload after 12 months, addresses after 90 days
+- [ ] Gateway with signature check, worker with dedupe
+- [ ] Read API with 5 second cache
+- [ ] Notifications on out_for_delivery and delivered
+- [ ] Load test at 600 events per second, onboard three pilot shops
+
+## 7. Risks
+
+| Risk | Likelihood | Mitigation |
+|------|------------|------------|
+| Carrier sends events out of order | High | Order by occurred_at, never by receive time |
+| Queue outage stops status updates | Low | Gateway buffers to disk for 10 minutes, alert on queue age |
+| Provider rate limits notifications | Medium | Batch and back off, drop to email only |
+
+## 8. Open questions
+
+- Public tracking page without login? Recommended: yes, with an unguessable id.
+- Retention for event payloads? Recommended: 12 months.

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/bugfix/meta.json

@@ -0,0 +1 @@
+{"id":"bugfix","label":"Bug fix","description":"Reproduction, root cause, fix plan, diff and regression test for one defect.","useWhen":"You are fixing a defect and want the cause, the fix and the proof written down before coding.","hasBoard":false}

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/bugfix/plan.mdx

@@ -0,0 +1,105 @@
+---
+title: Fix duplicate invoice emails
+status: draft
+needs-fix: repro
+needs-test: fix
+needs-rollout: fix, test
+---
+
+# Fix: duplicate invoice emails
+
+<Callout tone="note" title="How to use this template">
+
+Replace the Ledgerly example with your bug: rewrite the symptom, the reproduction steps, the root cause with real file paths, the Diff with the actual before and after, and the regression test. Keep the sections in this order, a reviewer reads top to bottom. All names here are invented.
+
+</Callout>
+
+## Symptom
+
+Ledgerly is a fictional invoicing service. Since release 2.14 some customers receive the same invoice email two or three times. Support counted 38 reports in nine days, all for invoices sent from the scheduled run at 06:00 UTC.
+
+- Affected: scheduled invoices only, manual sends are fine.
+- Impact: customer confusion, no double charge.
+- Severity: medium, no data loss.
+
+## Reproduction {#repro}
+
+<Table title="Steps" columns={["Step", "Action", "Expected", "Actual"]} rows={[
+  ["1", "Create an invoice scheduled for 06:00 UTC", "Status scheduled", "Status scheduled"],
+  ["2", "Start two scheduler workers", "Both idle", "Both idle"],
+  ["3", "Let the 06:00 tick fire", "One email", "Two emails"],
+  ["4", "Check the invoice row", "sent_at set once", "sent_at set twice, 40 ms apart"],
+]} />
+
+Reproduces locally in about one run in three with two workers and an artificial 50 ms delay in the mail client.
+
+## Root cause
+
+The scheduler selects due invoices and sends them in two separate steps. Two workers can select the same row before either marks it as sent.
+
+<Mermaid label="Race between two workers" source={"sequenceDiagram\n  participant W1 as Worker 1\n  participant DB as Database\n  participant W2 as Worker 2\n  W1->>DB: SELECT due invoices\n  W2->>DB: SELECT due invoices\n  DB-->>W1: invoice 4012\n  DB-->>W2: invoice 4012\n  W1->>W1: send email\n  W2->>W2: send email\n  W1->>DB: UPDATE sent_at\n  W2->>DB: UPDATE sent_at"} />
+
+<Callout tone="warning" title="Why it appeared in 2.14">
+
+Release 2.14 raised the worker count from one to three. With one worker the race could not happen, so the missing claim step went unnoticed for two years.
+
+</Callout>
+
+## Fix plan {#fix}
+
+Claim the row atomically before sending. The claim is a single UPDATE that only succeeds for one worker.
+
+<Decision title="How do we claim an invoice?" question="Which mechanism prevents two workers from sending the same invoice?" options={[
+  { id: "claim", label: "Atomic claim with UPDATE ... WHERE status = 'scheduled'", detail: "One statement, no new infrastructure, safe across workers.", recommended: true },
+  { id: "lock", label: "Advisory lock per invoice", detail: "Works, but the lock must be released on every error path." },
+  { id: "single", label: "Back to one worker", detail: "Hides the bug and loses the throughput gain." },
+]}>
+
+The atomic claim fixes the cause in the one place every send path goes through, and a crashed worker is recovered by a timeout on the claim.
+
+</Decision>
+
+<Diff filename="server/scheduler/send-due.ts" language="typescript" summary="Claim before send" before={"const due = await db.invoices.findDue(now);\nfor (const inv of due) {\n  await mailer.send(inv);\n  await db.invoices.markSent(inv.id, now);\n}"} after={"const due = await db.invoices.findDue(now);\nfor (const inv of due) {\n  const claimed = await db.invoices.claim(inv.id, workerId, now);\n  if (!claimed) continue;\n  await mailer.send(inv);\n  await db.invoices.markSent(inv.id, now);\n}"} />
+
+<ImplementationMap files={[
+  { path: "server/scheduler/send-due.ts", change: "modified", note: "Claim each invoice before sending" },
+  { path: "server/db/invoices.ts", change: "modified", note: "claim(): UPDATE status to sending, only from scheduled" },
+  { path: "server/db/migrations/031_invoice_claim.sql", change: "added", note: "claimed_by and claimed_at columns" },
+]} />
+
+## Regression test {#test}
+
+<Code filename="server/scheduler/send-due.test.ts" language="typescript" code={"test('two workers send an invoice once', async () => {\n  const inv = await seedScheduledInvoice();\n  await Promise.all([runWorker('w1'), runWorker('w2')]);\n  expect(mailer.sent).toHaveLength(1);\n  expect(await db.invoices.get(inv.id)).toMatchObject({ status: 'sent' });\n});"} />
+
+<Checklist title="Test plan" items={[
+  { label: "Test fails on the current main branch" },
+  { label: "Test passes with the fix, 200 runs in a row" },
+  { label: "Crashed worker: claim expires after 5 minutes and the invoice is retried" },
+  { label: "Manual send path is unchanged" },
+]} />
+
+## Rollout {#rollout}
+
+<Checklist title="Rollout tasks" items={[
+  { label: "Run migration 031 before deploying the code" },
+  { label: "Deploy and watch duplicate-send alert for one day" },
+  { label: "Reply to the 38 affected tickets" },
+]} />
+
+<AgentTrail />
+
+## Risks
+
+<Table title="Risks" columns={["Risk", "Mitigation"]} rows={[
+  ["A crashed worker leaves invoices stuck in sending", "Claim expires after 5 minutes, a sweep resets it to scheduled"],
+  ["Migration locks the invoices table", "Add nullable columns only, no backfill"],
+]} />
+
+## Open questions
+
+<QuestionForm title="Open Questions" questions={[
+  { title: "Should customers who got duplicates receive an apology email?", mode: "single", options: [
+    { label: "No, a support reply is enough", recommended: true }, { label: "Yes, one short email" } ] },
+  { title: "Add an idempotency key to the mail provider call as well?", mode: "single", options: [
+    { label: "Yes, as a follow-up", recommended: true }, { label: "Not needed" } ] },
+]} />

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/bugfix/standard.md

@@ -0,0 +1,76 @@
+# Fix: duplicate invoice emails
+
+> **How to use this template:** replace the Ledgerly example with your bug. Rewrite the symptom, reproduction, root cause, fix and regression test. All names here are invented.
+
+**Status:** draft  **Severity:** medium, no data loss
+
+## 1. Symptom
+
+Ledgerly is a fictional invoicing service. Since release 2.14 some customers receive the same invoice email two or three times. Support counted 38 reports in nine days, all for invoices sent by the scheduled run at 06:00 UTC.
+
+## 2. Reproduction
+
+| Step | Action | Expected | Actual |
+|------|--------|----------|--------|
+| 1 | Create an invoice scheduled for 06:00 UTC | Status scheduled | Status scheduled |
+| 2 | Start two scheduler workers | Both idle | Both idle |
+| 3 | Let the 06:00 tick fire | One email | Two emails |
+| 4 | Check the invoice row | sent_at set once | sent_at set twice, 40 ms apart |
+
+Reproduces about one run in three with two workers and a 50 ms delay in the mail client.
+
+## 3. Root cause
+
+The scheduler selects due invoices and sends them in two separate steps. Two workers can select the same row before either marks it as sent. Release 2.14 raised the worker count from one to three, which exposed the race.
+
+```mermaid
+sequenceDiagram
+  participant W1 as Worker 1
+  participant DB as Database
+  participant W2 as Worker 2
+  W1->>DB: SELECT due invoices
+  W2->>DB: SELECT due invoices
+  DB-->>W1: invoice 4012
+  DB-->>W2: invoice 4012
+  W1->>W1: send email
+  W2->>W2: send email
+  W1->>DB: UPDATE sent_at
+  W2->>DB: UPDATE sent_at
+```
+
+## 4. Fix plan
+
+| Option | Verdict |
+|--------|---------|
+| **Atomic claim with UPDATE ... WHERE status = 'scheduled'** | Recommended: one statement, no new infrastructure |
+| Advisory lock per invoice | Lock must be released on every error path |
+| Back to one worker | Hides the bug, loses throughput |
+
+Change in `server/scheduler/send-due.ts`: call `db.invoices.claim(id, workerId, now)` before sending and skip the invoice when the claim fails. Add `claimed_by` and `claimed_at` columns in migration 031.
+
+## 5. Regression test
+
+- [ ] Test fails on the current main branch
+- [ ] Test passes with the fix, 200 runs in a row
+- [ ] Crashed worker: claim expires after 5 minutes and the invoice is retried
+- [ ] Manual send path is unchanged
+
+Test: seed one scheduled invoice, run two workers at once, expect exactly one email and status sent.
+
+## 6. Rollout
+
+- [ ] Run migration 031 before deploying the code
+- [ ] Deploy and watch the duplicate-send alert for one day
+- [ ] Reply to the 38 affected tickets
+
+## 7. Risks
+
+| Risk | Mitigation |
+|------|------------|
+| A crashed worker leaves invoices stuck in sending | Claim expires after 5 minutes, a sweep resets it |
+| Migration locks the invoices table | Nullable columns only, no backfill |
+
+## 8. Open questions
+
+- Apology email for affected customers? Recommended: no, a support reply is enough.
+- Add an idempotency key to the mail provider call? Recommended: yes, as a follow-up.

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/feature/canvas.mdx

@@ -0,0 +1,81 @@
+<DesignBoard title="Trailmark - Saved Routes storyboard" version={1} transitions={[
+  { from: "map", to: "save", label: "Tap Save" },
+  { from: "save", to: "list", label: "Save route" },
+  { from: "list", to: "detail", label: "Open a route" },
+  { from: "detail", to: "list", label: "Remove" },
+]}>
+<Section title="1 Save and revisit" subtitle="From the map to a saved route. Low-fidelity sketches, not final UI.">
+<Artboard id="map" label="Map" surface="mobile" x={80} y={120} width={320} height={480} order={1}>
+<Screen surface="mobile" caption="Route selected on the map.">
+  <FrameScreen>
+    <StatusBar />
+    <Title text="Ridge Loop" />
+    <Text value="9.4 km, 3 h 10 min" tone="muted" />
+    <Box full dashed>
+      <Text value="Map preview" tone="muted" />
+    </Box>
+    <Row>
+      <Btn label="Start" primary />
+      <Btn label="Save" />
+    </Row>
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="save" label="Save sheet" surface="mobile" x={480} y={120} width={320} height={480} order={2}>
+<Screen surface="mobile" caption="Bottom sheet over the map.">
+  <FrameScreen>
+    <StatusBar />
+    <Title text="Save route" />
+    <Box>
+      <Text value="Name" tone="muted" />
+      <Text value="Ridge Loop" />
+    </Box>
+    <TaskRow title="Keep available offline" done />
+    <TaskRow title="Sync to my other devices" done />
+    <Divider />
+    <Btn label="Save route" primary />
+    <Btn label="Cancel" />
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="list" label="Saved list" surface="mobile" x={880} y={120} width={320} height={480} order={3}>
+<Screen surface="mobile" caption="Works in airplane mode.">
+  <FrameScreen>
+    <StatusBar />
+    <Title text="Saved routes" />
+    <Chips items={[{"label":"Recent","active":true},{"label":"Nearby"},{"label":"A-Z"}]} />
+    <Card>
+      <Text value="Ridge Loop" weight="bold" />
+      <Text value="9.4 km, synced" tone="muted" />
+    </Card>
+    <Card>
+      <Text value="Lake Shore Walk" weight="bold" />
+      <Text value="4.1 km, pending" tone="muted" />
+    </Card>
+    <Card>
+      <Text value="Quarry Climb" weight="bold" />
+      <Text value="12.8 km, synced" tone="muted" />
+    </Card>
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="detail" label="Route detail" surface="mobile" x={1280} y={120} width={320} height={480} order={4}>
+<Screen surface="mobile" caption="Remove is a text button, not a trash icon.">
+  <FrameScreen>
+    <StatusBar />
+    <Title text="Ridge Loop" />
+    <Box full dashed>
+      <Text value="Map preview" tone="muted" />
+    </Box>
+    <Row>
+      <Text value="9.4 km" weight="bold" />
+      <Text value="620 m up" tone="muted" />
+    </Row>
+    <Btn label="Start" primary />
+    <Btn label="Remove from saved" />
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Annotation targetId="list" title="Sync state">Each row shows synced or pending so a hiker knows what a second device will see.</Annotation>
+</Section>
+</DesignBoard>

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/templates/feature/meta.json

@@ -0,0 +1 @@
+{"id":"feature","label":"New feature","description":"A product feature with screens, a storyboard board, decisions, build map and open questions.","useWhen":"You are planning a user-facing feature that needs 3-4 screens and a clear build order.","hasBoard":true}