Merge branch 'refactor/task-04b-chapters-data'

src/content/chapters/agents.json

@@ -0,0 +1,76 @@
+{
+  "id": "agents",
+  "eyebrow": { "en": "Subagent workflow", "pt": "Subagent workflow" },
+  "title": { "en": "One branch<br>per <em>hand.</em>", "pt": "One branch<br>per <em>hand.</em>" },
+  "lede": {
+    "en": "Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.",
+    "pt": "Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent."
+  },
+  "cards": [
+    {
+      "label": { "en": "FRAME", "pt": "FRAME" },
+      "title": { "en": "Orchestrator", "pt": "Orchestrator" },
+      "copy": {
+        "en": "Owns scope, task graph, boundaries, and integration.",
+        "pt": "Owns scope, task graph, boundaries, and integration."
+      }
+    },
+    {
+      "label": { "en": "HAND OFF", "pt": "HAND OFF" },
+      "title": { "en": "Worker", "pt": "Worker" },
+      "copy": {
+        "en": "Owns one coherent slice and one worktree.",
+        "pt": "Owns one coherent slice and one worktree."
+      }
+    },
+    {
+      "label": { "en": "PROVE", "pt": "PROVE" },
+      "title": { "en": "Verifier", "pt": "Verifier" },
+      "copy": {
+        "en": "Re-runs gates and reports remaining gaps.",
+        "pt": "Re-runs gates and reports remaining gaps."
+      }
+    }
+  ],
+  "sections": [
+    {
+      "eyebrow": { "en": "The tree", "pt": "The tree" },
+      "title": { "en": "Split at<br>the <em>seam.</em>", "pt": "Split at<br>the <em>seam.</em>" },
+      "panelLabel": { "en": "MAIN / ORCHESTRATOR", "pt": "MAIN / ORCHESTRATOR" },
+      "panelCode": {
+        "en": "├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence",
+        "pt": "├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence"
+      }
+    },
+    {
+      "eyebrow": { "en": "Handoff", "pt": "Handoff" },
+      "title": {
+        "en": "Context that<br>can <em>travel.</em>",
+        "pt": "Context that<br>can <em>travel.</em>"
+      },
+      "steps": [
+        {
+          "label": { "en": "Brief", "pt": "Brief" },
+          "copy": {
+            "en": "Goal, owned files, dependencies, non-goals, acceptance.",
+            "pt": "Goal, owned files, dependencies, non-goals, acceptance."
+          }
+        },
+        {
+          "label": { "en": "Isolation", "pt": "Isolation" },
+          "copy": {
+            "en": "One branch and worktree per independent change.",
+            "pt": "One branch and worktree per independent change."
+          }
+        },
+        {
+          "label": { "en": "Evidence", "pt": "Evidence" },
+          "copy": {
+            "en": "Commands, result, changed files, screenshots, gaps.",
+            "pt": "Commands, result, changed files, screenshots, gaps."
+          }
+        }
+      ]
+    }
+  ]
+}

src/content/chapters/landing.json

@@ -0,0 +1,83 @@
+{
+  "id": "landing",
+  "eyebrow": { "en": "The short route", "pt": "The short route" },
+  "title": { "en": "Ship the<br><em>system.</em>", "pt": "Ship the<br><em>system.</em>" },
+  "lede": {
+    "en": "Start with the map. Then open the one chapter that matches the decision in front of you: model, agent, worktree, skill, rule, or proof.",
+    "pt": "Start with the map. Then open the one chapter that matches the decision in front of you: model, agent, worktree, skill, rule, or proof."
+  },
+  "threadLabel": {
+    "en": "THE THREAD",
+    "pt": "THE THREAD"
+  },
+  "threadText": {
+    "en": "Frame uncertainty → isolate execution → preserve judgment → verify the change.",
+    "pt": "Frame uncertainty → isolate execution → preserve judgment → verify the change."
+  },
+  "footer": {
+    "en": "The route map is now the default entry. The full guide remains available whenever you want the whole narrative.",
+    "pt": "The route map is now the default entry. The full guide remains available whenever you want the whole narrative."
+  },
+  "cards": [
+    {
+      "label": { "en": "01", "pt": "01" },
+      "title": { "en": "Models", "pt": "Models" },
+      "copy": {
+        "en": "Capability and effort are separate knobs.",
+        "pt": "Capability and effort are separate knobs."
+      },
+      "href": "models/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "02", "pt": "02" },
+      "title": { "en": "Agents & trees", "pt": "Agents & trees" },
+      "copy": {
+        "en": "Bound roles, handoffs, and worktrees.",
+        "pt": "Bound roles, handoffs, and worktrees."
+      },
+      "href": "agents/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "03", "pt": "03" },
+      "title": { "en": "Skills", "pt": "Skills" },
+      "copy": {
+        "en": "Capture repeatable decisions in small packages.",
+        "pt": "Capture repeatable decisions in small packages."
+      },
+      "href": "skills/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "04", "pt": "04" },
+      "title": { "en": "Rules", "pt": "Rules" },
+      "copy": {
+        "en": "Connect guidance to enforcement.",
+        "pt": "Connect guidance to enforcement."
+      },
+      "href": "rules/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "05", "pt": "05" },
+      "title": { "en": "Hands-on", "pt": "Hands-on" },
+      "copy": {
+        "en": "Compare a strong prompt with skill-enabled work.",
+        "pt": "Compare a strong prompt with skill-enabled work."
+      },
+      "href": "hands-on/starter/",
+      "cta": { "en": "Open lab →", "pt": "Open lab →" }
+    },
+    {
+      "label": { "en": "06", "pt": "06" },
+      "title": { "en": "Review desk", "pt": "Review desk" },
+      "copy": {
+        "en": "Browse original packages, references, scripts, and improvements.",
+        "pt": "Browse original packages, references, scripts, and improvements."
+      },
+      "href": "skills-review/",
+      "cta": { "en": "Open desk →", "pt": "Open desk →" }
+    }
+  ]
+}

src/content/chapters/models.json

@@ -0,0 +1,76 @@
+{
+  "id": "models",
+  "eyebrow": { "en": "Model routing", "pt": "Model routing" },
+  "title": { "en": "Choose the<br><em>engine.</em>", "pt": "Choose the<br><em>engine.</em>" },
+  "lede": {
+    "en": "A model has a capability ceiling. Effort controls how much room it gets to reason. Route by uncertainty and verification cost.",
+    "pt": "A model has a capability ceiling. Effort controls how much room it gets to reason. Route by uncertainty and verification cost."
+  },
+  "cards": [
+    {
+      "label": { "en": "LOW", "pt": "LOW" },
+      "title": { "en": "Bounded rhythm", "pt": "Bounded rhythm" },
+      "copy": {
+        "en": "Lookup, small edits, formatting, and transformations with clear checks.",
+        "pt": "Lookup, small edits, formatting, and transformations with clear checks."
+      }
+    },
+    {
+      "label": { "en": "MEDIUM", "pt": "MEDIUM" },
+      "title": { "en": "Default work", "pt": "Default work" },
+      "copy": {
+        "en": "Normal implementation where the contract is clear but context matters.",
+        "pt": "Normal implementation where the contract is clear but context matters."
+      }
+    },
+    {
+      "label": { "en": "HIGH", "pt": "HIGH" },
+      "title": { "en": "Ambiguity", "pt": "Ambiguity" },
+      "copy": {
+        "en": "Planning, architecture, security judgment, and hard failures.",
+        "pt": "Planning, architecture, security judgment, and hard failures."
+      }
+    }
+  ],
+  "sections": [
+    {
+      "eyebrow": { "en": "Two knobs", "pt": "Two knobs" },
+      "title": { "en": "Capability<br>× effort", "pt": "Capability<br>× effort" },
+      "panelLabel": { "en": "ROUTING RULE", "pt": "ROUTING RULE" },
+      "panelCode": {
+        "en": "strong model + high effort → frame ambiguity · light model + low effort → bounded execution · raise one knob at a time → compare evidence",
+        "pt": "strong model + high effort → frame ambiguity · light model + low effort → bounded execution · raise one knob at a time → compare evidence"
+      }
+    },
+    {
+      "eyebrow": { "en": "Sequence", "pt": "Sequence" },
+      "title": {
+        "en": "Spend judgment<br>where it <em>compounds.</em>",
+        "pt": "Spend judgment<br>where it <em>compounds.</em>"
+      },
+      "steps": [
+        {
+          "label": { "en": "Plan", "pt": "Plan" },
+          "copy": {
+            "en": "Strong model: scope, risks, acceptance, and worktree split.",
+            "pt": "Strong model: scope, risks, acceptance, and worktree split."
+          }
+        },
+        {
+          "label": { "en": "Build", "pt": "Build" },
+          "copy": {
+            "en": "Focused worker: smallest context and lightest model that can pass.",
+            "pt": "Focused worker: smallest context and lightest model that can pass."
+          }
+        },
+        {
+          "label": { "en": "Review", "pt": "Review" },
+          "copy": {
+            "en": "Independent pass when missed issues cost more than the call.",
+            "pt": "Independent pass when missed issues cost more than the call."
+          }
+        }
+      ]
+    }
+  ]
+}

src/content/chapters/skills.json

@@ -0,0 +1,59 @@
+{
+  "id": "skills",
+  "eyebrow": { "en": "Reusable judgment", "pt": "Reusable judgment" },
+  "title": { "en": "Teach the<br><em>decision.</em>", "pt": "Teach the<br><em>decision.</em>" },
+  "lede": {
+    "en": "A skill changes behavior. Keep the trigger precise, put the workflow in <code>SKILL.md</code>, and move conditional facts, scripts, and examples into focused files.",
+    "pt": "A skill changes behavior. Keep the trigger precise, put the workflow in <code>SKILL.md</code>, and move conditional facts, scripts, and examples into focused files."
+  },
+  "sections": [
+    {
+      "eyebrow": { "en": "Package anatomy", "pt": "Package anatomy" },
+      "title": {
+        "en": "One job.<br>More than<br>one <em>file.</em>",
+        "pt": "One job.<br>More than<br>one <em>file.</em>"
+      },
+      "copy": {
+        "en": "Choose a file to see why it belongs in the package.",
+        "pt": "Choose a file to see why it belongs in the package."
+      }
+    },
+    {
+      "eyebrow": { "en": "Create a skill", "pt": "Create a skill" },
+      "title": {
+        "en": "Observe →<br>trigger →<br>validate",
+        "pt": "Observe →<br>trigger →<br>validate"
+      },
+      "steps": [
+        {
+          "label": { "en": "Observe friction", "pt": "Observe friction" },
+          "copy": {
+            "en": "Find a repeated decision or failure.",
+            "pt": "Find a repeated decision or failure."
+          }
+        },
+        {
+          "label": { "en": "Define the trigger", "pt": "Define the trigger" },
+          "copy": {
+            "en": "Say when it should load and when it should stay out.",
+            "pt": "Say when it should load and when it should stay out."
+          }
+        },
+        {
+          "label": { "en": "Choose anatomy", "pt": "Choose anatomy" },
+          "copy": {
+            "en": "Use references for facts and scripts for deterministic mechanics.",
+            "pt": "Use references for facts and scripts for deterministic mechanics."
+          }
+        },
+        {
+          "label": { "en": "Evaluate behavior", "pt": "Evaluate behavior" },
+          "copy": {
+            "en": "Test realistic prompts, edge cases, safety, and evidence.",
+            "pt": "Test realistic prompts, edge cases, safety, and evidence."
+          }
+        }
+      ]
+    }
+  ]
+}

src/content/chapters/summary.json

@@ -0,0 +1,75 @@
+{
+  "id": "summary",
+  "eyebrow": { "en": "Start here", "pt": "Start here" },
+  "title": { "en": "Ship the<br><em>system.</em>", "pt": "Ship the<br><em>system.</em>" },
+  "lede": {
+    "en": "This guide turns AI work into a shape: frame the problem, choose the model and agent, isolate changes, teach repeatable decisions, and verify the result.",
+    "pt": "This guide turns AI work into a shape: frame the problem, choose the model and agent, isolate changes, teach repeatable decisions, and verify the result."
+  },
+  "footer": {
+    "en": "Each chapter stands alone; the order follows a real task becoming a reliable change.",
+    "pt": "Each chapter stands alone; the order follows a real task becoming a reliable change."
+  },
+  "cards": [
+    {
+      "label": { "en": "01", "pt": "01" },
+      "title": { "en": "Models", "pt": "Models" },
+      "copy": {
+        "en": "Capability and effort are separate knobs.",
+        "pt": "Capability and effort are separate knobs."
+      },
+      "href": "../models/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "02", "pt": "02" },
+      "title": { "en": "Agents & trees", "pt": "Agents & trees" },
+      "copy": {
+        "en": "Bound roles, handoffs, and worktrees.",
+        "pt": "Bound roles, handoffs, and worktrees."
+      },
+      "href": "../agents/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "03", "pt": "03" },
+      "title": { "en": "Skills", "pt": "Skills" },
+      "copy": {
+        "en": "Capture repeatable decisions.",
+        "pt": "Capture repeatable decisions."
+      },
+      "href": "../skills/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "04", "pt": "04" },
+      "title": { "en": "Rules", "pt": "Rules" },
+      "copy": {
+        "en": "Connect guidance to enforcement.",
+        "pt": "Connect guidance to enforcement."
+      },
+      "href": "../rules/",
+      "cta": { "en": "Open chapter →", "pt": "Open chapter →" }
+    },
+    {
+      "label": { "en": "05", "pt": "05" },
+      "title": { "en": "Practice", "pt": "Practice" },
+      "copy": {
+        "en": "Compare prompts and skill-enabled runs.",
+        "pt": "Compare prompts and skill-enabled runs."
+      },
+      "href": "../hands-on/starter/",
+      "cta": { "en": "Open lab →", "pt": "Open lab →" }
+    },
+    {
+      "label": { "en": "06", "pt": "06" },
+      "title": { "en": "Review desk", "pt": "Review desk" },
+      "copy": {
+        "en": "Browse original files and improved drafts.",
+        "pt": "Browse original files and improved drafts."
+      },
+      "href": "../skills-review/",
+      "cta": { "en": "Open desk →", "pt": "Open desk →" }
+    }
+  ]
+}

src/content/config.ts

@@ -92,9 +92,23 @@ const skillInstallPrompts = defineCollection({
   }),
 });
 
-// Chapter copy for /models/, /agents/, /skills/, /summary/. The body of
+// Chapter copy for /models/, /agents/, /skills/, /summary/ and the landing
-// each page composes one or more sections; the field names mirror what the
+// route map. The body of each page composes one or more sections; the
-// existing HTML already says aloud (eyebrow / lede / card titles).
+// field names mirror what the existing HTML already says aloud (eyebrow /
+// lede / card titles).
+//
+// `cards[].href` and `cards[].cta` were added in task 04b: the landing
+// route map's six cards have non-uniform call-to-action text (four read
+// "Open chapter →", one "Open lab →", one "Open desk →"), so a single
+// hard-coded default would be wrong. `href` is the destination; `cta` is
+// the localized link text.
+//
+// `sections[].panelLabel` / `panelCode` / `panelHint` carry the highlighted
+// rule panels on /models/, /agents/, and /skills/ (the routing rule, the
+// MAIN / ORCHESTRATOR tree, and the package-anatomy hint).
+//
+// `threadLabel` / `threadText` and `footer` carry the landing-page thread
+// strip and footer line.
 const chapters = defineCollection({
   type: 'data',
   schema: z.object({
@@ -102,12 +116,17 @@ const chapters = defineCollection({
     eyebrow: localized,
     title: localized,
     lede: localized,
+    threadLabel: localized.optional(),
+    threadText: localized.optional(),
+    footer: localized.optional(),
     cards: z
       .array(
         z.object({
           label: localized,
           title: localized,
           copy: localized,
+          href: z.string().optional(),
+          cta: localized.optional(),
         }),
       )
       .optional(),
@@ -117,6 +136,9 @@ const chapters = defineCollection({
           eyebrow: localized.optional(),
           title: localized,
           copy: localized.optional(),
+          panelLabel: localized.optional(),
+          panelCode: localized.optional(),
+          panelHint: localized.optional(),
           steps: z
             .array(
               z.object({