diff --git a/src/content/chapters/agents.json b/src/content/chapters/agents.json new file mode 100644 index 0000000..45e00db --- /dev/null +++ b/src/content/chapters/agents.json @@ -0,0 +1,76 @@ +{ + "id": "agents", + "eyebrow": { "en": "Subagent workflow", "pt": "Subagent workflow" }, + "title": { "en": "One branch
per hand.", "pt": "One branch
per hand." }, + "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
the seam.", "pt": "Split at
the seam." }, + "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
can travel.", + "pt": "Context that
can travel." + }, + "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." + } + } + ] + } + ] +} diff --git a/src/content/chapters/landing.json b/src/content/chapters/landing.json new file mode 100644 index 0000000..a51dd37 --- /dev/null +++ b/src/content/chapters/landing.json @@ -0,0 +1,83 @@ +{ + "id": "landing", + "eyebrow": { "en": "The short route", "pt": "The short route" }, + "title": { "en": "Ship the
system.", "pt": "Ship the
system." }, + "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 →" } + } + ] +} diff --git a/src/content/chapters/models.json b/src/content/chapters/models.json new file mode 100644 index 0000000..bc690af --- /dev/null +++ b/src/content/chapters/models.json @@ -0,0 +1,76 @@ +{ + "id": "models", + "eyebrow": { "en": "Model routing", "pt": "Model routing" }, + "title": { "en": "Choose the
engine.", "pt": "Choose the
engine." }, + "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
× effort", "pt": "Capability
× 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
where it compounds.", + "pt": "Spend judgment
where it compounds." + }, + "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." + } + } + ] + } + ] +} diff --git a/src/content/chapters/skills.json b/src/content/chapters/skills.json new file mode 100644 index 0000000..7847d2a --- /dev/null +++ b/src/content/chapters/skills.json @@ -0,0 +1,59 @@ +{ + "id": "skills", + "eyebrow": { "en": "Reusable judgment", "pt": "Reusable judgment" }, + "title": { "en": "Teach the
decision.", "pt": "Teach the
decision." }, + "lede": { + "en": "A skill changes behavior. Keep the trigger precise, put the workflow in SKILL.md, and move conditional facts, scripts, and examples into focused files.", + "pt": "A skill changes behavior. Keep the trigger precise, put the workflow in SKILL.md, and move conditional facts, scripts, and examples into focused files." + }, + "sections": [ + { + "eyebrow": { "en": "Package anatomy", "pt": "Package anatomy" }, + "title": { + "en": "One job.
More than
one file.", + "pt": "One job.
More than
one file." + }, + "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 →
trigger →
validate", + "pt": "Observe →
trigger →
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." + } + } + ] + } + ] +} diff --git a/src/content/chapters/summary.json b/src/content/chapters/summary.json new file mode 100644 index 0000000..e003bef --- /dev/null +++ b/src/content/chapters/summary.json @@ -0,0 +1,75 @@ +{ + "id": "summary", + "eyebrow": { "en": "Start here", "pt": "Start here" }, + "title": { "en": "Ship the
system.", "pt": "Ship the
system." }, + "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 →" } + } + ] +} diff --git a/src/content/config.ts b/src/content/config.ts index 5658bf1..ccefe1c 100644 --- a/src/content/config.ts +++ b/src/content/config.ts @@ -92,9 +92,23 @@ const skillInstallPrompts = defineCollection({ }), }); -// Chapter copy for /models/, /agents/, /skills/, /summary/. The body of -// each page composes one or more sections; the field names mirror what the -// existing HTML already says aloud (eyebrow / lede / card titles). +// Chapter copy for /models/, /agents/, /skills/, /summary/ and the landing +// route map. The body of each page composes one or more sections; the +// 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({