From aa858648687912561a1566e365f2742f1ff902d4 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Fri, 4 Sep 2026 04:18:15 +0000 Subject: [PATCH] feat: make route map the interactive landing page --- GATES.md | 34 ++++++++++++-------------- README.md | 8 +++--- agents/index.html | 2 +- docs/operations-guide.md | 8 +++--- full-guide/audit.css | 26 ++++++++++++++++++++ full-guide/index.html | 37 ++++++++++++++++++++++++++++ index.html | 53 +++++++++++++++++----------------------- landing.css | 1 + models/index.html | 2 +- scripts/audit-ui.mjs | 18 ++++++++++++++ scripts/verify.mjs | 19 +++++++++++--- skills/app.js | 23 +++++++++++++++++ skills/index.html | 34 +++++++++++++++++++++++++- skills/styles.css | 1 + summary/index.html | 2 +- 15 files changed, 203 insertions(+), 65 deletions(-) create mode 100644 full-guide/audit.css create mode 100644 full-guide/index.html create mode 100644 landing.css create mode 100644 scripts/audit-ui.mjs create mode 100644 skills/app.js create mode 100644 skills/styles.css diff --git a/GATES.md b/GATES.md index e05c9c1..188edd1 100644 --- a/GATES.md +++ b/GATES.md @@ -1,27 +1,23 @@ -# Gates: Rules and enforcement case study +# Gates: responsive chapter audit and summary landing -OWNS: rules/**, index.html, README.md, docs/operations-guide.md, scripts/verify.mjs +OWNS: index.html, full-guide/**, chapters.css, skills/index.html, skills/app.js, scripts/verify.mjs, scripts/audit-ui.mjs -Scope: Add a concise bilingual page that explains how `netcracker/interview` -combines agent context, reusable skills, CLI checks, Husky hooks, and PR review. +Scope: Make the route map the default entry point, repair the skills package anatomy layout, add purposeful interactions, and verify the guide across responsive, desktop, and accessibility-critical viewports. -- [ ] G1: separate rules page presents repository-grounded summary and examples +- [x] G1: root entry directs readers to the summary while the full guide remains available at a stable route CHECK: node scripts/verify.mjs - EXPECT: rules content verification passed - EVIDENCE: pending + EXPECT: landing route verification passed + EVIDENCE: `node scripts/verify.mjs` on 2026-09-04 emitted `landing route verification passed`. -- [ ] G2: pipeline, skill examples, language switch, and copy controls work +- [x] G2: the skill package anatomy renders as a readable tree with one node per line and selectable file previews CHECK: node scripts/verify.mjs - EXPECT: rules interaction verification passed - EVIDENCE: pending + EXPECT: skills anatomy verification passed + EVIDENCE: `node scripts/verify.mjs` on 2026-09-04 emitted `skills anatomy verification passed`; Playwright selected all four package files. -- [ ] G3: page is dependency-free and linked from the main presentation +- [x] G3: public pages reflow without horizontal overflow and retain usable navigation at compact through 4K viewports + EVIDENCE: Playwright audit on 2026-09-04: 10 public routes × 320, 390, 1280, 1920, and 3840px; no horizontal overflow, HTTP failures, page errors, or failed skills-package selections. + +- [x] G4: repository verification covers the landing route, skills anatomy, and interaction contracts CHECK: node scripts/verify.mjs - EXPECT: rules standalone verification passed - EVIDENCE: pending - -- [ ] G4: mobile, Full HD, and 4K browser checks pass without overflow or errors - EVIDENCE: pending - -- [ ] G5: main and pages point to one commit and the live rules endpoint serves it - EVIDENCE: pending + EXPECT: presentation verification passed + EVIDENCE: `node scripts/verify.mjs` and `node scripts/audit-ui.mjs` passed on 2026-09-04. diff --git a/README.md b/README.md index 97a00a5..e601ba1 100644 --- a/README.md +++ b/README.md @@ -32,16 +32,16 @@ npm run verify ## Project structure -- `index.html` — presentation content and semantic structure -- `styles.css` — editorial visual system and responsive layout -- `app.js` — bilingual workflow, repository-tree, routing, and skill interactions +- `index.html` — default route map and focused chapter navigation +- `full-guide/` — the complete bilingual presentation, with responsive audit overrides +- `styles.css` / `app.js` — editorial visual system and bilingual field-guide interactions - `responsive.css` — interactive diagrams and Full HD-to-4K adaptations - `docs/references/` — bundled research sources and notes - `docs/operations-guide.md` — canonical SilverBullet operations and skills guide - `hands-on/starter/` — dependency-free Tiny Tasks exercise - `hands-on/rules/` — dependency-free Guardrails lab; toggles rule sources into the prompt - `rules/` — bilingual case study of skills, CLI ratchets, Husky, and PR review -- `skills/` — reusable design and rules-case-study skills extracted from this implementation +- `skills/` — reusable design and rules-case-study skills, plus an interactive package anatomy explorer - `GATES.md` — acceptance ledger for the project ## Publishing diff --git a/agents/index.html b/agents/index.html index ee4d1f3..ce8da42 100644 --- a/agents/index.html +++ b/agents/index.html @@ -1 +1 @@ -AI For Dummies — Agents and trees
← ROUTE MAP02 / AGENTS & TREESfield guide ↗

Subagent workflow

One branch
per hand.

Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.

The tree

Split at
the seam.

MAIN / ORCHESTRATOR├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence
FRAME

Orchestrator

Owns scope, task graph, boundaries, and integration.

HAND OFF

Worker

Owns one coherent slice and one worktree.

PROVE

Verifier

Re-runs gates and reports remaining gaps.

Handoff

Context that
can travel.

01
BriefGoal, owned files, dependencies, non-goals, acceptance.
02
IsolationOne branch and worktree per independent change.
03
EvidenceCommands, result, changed files, screenshots, gaps.
+AI For Dummies — Agents and trees
← ROUTE MAP02 / AGENTS & TREESfield guide ↗

Subagent workflow

One branch
per hand.

Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.

The tree

Split at
the seam.

MAIN / ORCHESTRATOR├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence
FRAME

Orchestrator

Owns scope, task graph, boundaries, and integration.

HAND OFF

Worker

Owns one coherent slice and one worktree.

PROVE

Verifier

Re-runs gates and reports remaining gaps.

Handoff

Context that
can travel.

01
BriefGoal, owned files, dependencies, non-goals, acceptance.
02
IsolationOne branch and worktree per independent change.
03
EvidenceCommands, result, changed files, screenshots, gaps.
diff --git a/docs/operations-guide.md b/docs/operations-guide.md index 326131f..9d7b05e 100644 --- a/docs/operations-guide.md +++ b/docs/operations-guide.md @@ -35,7 +35,8 @@ repository files directly; there is no bundler or generated `dist/` folder. | File | Responsibility | | :--- | :--- | -| `index.html` | Semantic sections, controls, labels, and English source copy | +| `index.html` | Default route map and focused chapter navigation | +| `full-guide/index.html` | Complete bilingual field guide, controls, labels, and English source copy | | `styles.css` | Base editorial visual system | | `responsive.css` | Interactive diagrams and Full HD, 4K, tablet, and mobile adaptations | | `app.js` | Interactions, state, and Portuguese translations | @@ -86,6 +87,7 @@ and one mobile viewport. ```bash npm run verify node --check app.js +node scripts/audit-ui.mjs git diff --check ``` @@ -100,7 +102,7 @@ standalone verification passed ### 4. Commit and push the source branch ```bash -git add README.md app.js index.html styles.css responsive.css scripts/verify.mjs docs/ +git add README.md app.js index.html full-guide/ styles.css responsive.css scripts/verify.mjs scripts/audit-ui.mjs docs/ git commit -m "feat: describe the change" git push origin main ``` @@ -148,7 +150,7 @@ certificate. ## Adding or changing a presentation section -1. Add semantic HTML and stable `data-*` hooks in `index.html`. +1. Add semantic HTML and stable `data-*` hooks in the focused chapter or `full-guide/index.html`; keep `index.html` as the short route map. 2. Put interactive content in a data object inside `app.js`. 3. Add one focused render function and bind its controls once. 4. Add Portuguese static copy to `translations.pt` and dynamic copy to the diff --git a/full-guide/audit.css b/full-guide/audit.css new file mode 100644 index 0000000..caf4c9e --- /dev/null +++ b/full-guide/audit.css @@ -0,0 +1,26 @@ +/* Responsive audit overrides: preserve the information, not a desktop-width table. */ +@media(max-width:800px){ + .skills>pre,.install-skills,.prompt-card,.verify-card{min-width:0;max-width:100%} + .skills>pre code,.install-skills code,.prompt-card code,.verify-card-source span{overflow-wrap:anywhere;word-break:break-word} + .hero-stats{grid-template-columns:minmax(0,1fr) minmax(0,1fr)} + .hero-stats div,.hero-stats p{min-width:0} + .handoff,.route-table{overflow:visible} + .handoff table{min-width:0;table-layout:fixed} + .handoff th,.handoff td{overflow-wrap:anywhere} + .route-table>div,.route-table button{min-width:0;grid-template-columns:minmax(0,.8fr) minmax(0,.9fr) minmax(0,1.4fr)} + .route-table>div>* ,.route-table button>*{min-width:0;overflow-wrap:anywhere} +} +@media(max-width:420px){ + .handoff table,.handoff thead,.handoff tbody,.handoff tr,.handoff th,.handoff td{display:block;width:100%} + .handoff thead{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)} + .handoff tbody tr{padding:14px 0;border-bottom:1px solid var(--line)} + .handoff th,.handoff td{padding:4px 0;border:0} + .handoff td::before{display:block;margin-top:7px;color:var(--blue);font:600 9px 'DM Mono',monospace;letter-spacing:.08em;text-transform:uppercase} + .handoff td:nth-child(2)::before{content:'Contains'} + .handoff td:nth-child(3)::before{content:'Why it matters'} + .route-table .head{display:none} + .route-table button{display:grid;grid-template-columns:1fr;gap:0} + .route-table button>*{padding:10px 12px;border-right:0} + .route-table button b::before{content:'Profile · ';color:var(--muted)} +} +@media(prefers-reduced-motion:reduce){.hero-stats,.handoff,.route-table{scroll-behavior:auto}} diff --git a/full-guide/index.html b/full-guide/index.html new file mode 100644 index 0000000..af74658 --- /dev/null +++ b/full-guide/index.html @@ -0,0 +1,37 @@ + + + + + + + + AI For Dummies — Field Guide + + + + + +
+
A field guide
review submissions ↗
/
AI ENGINEERING 01 / 2026
+

A presentation for humans who ship

AI for
dummies.

You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.

+
01strong model
for ambiguity
03bounded workers
in parallel
∞iterations
with evidence

Read this as a route map, not a prompt recipe.

+
RULE ZEROStrong model for ambiguity.
Light model for bounded work.
+
A small fleetcoordination before parallelism
ORCHESTRATOR

Decides what
needs to happen.

Opus / reasoning
→

The orchestrator preserves intent, writes small contracts, and gathers results that can be verified. It does not need to type every line.

+
Why the boundary mattersone vague task / three predictable failures
01Context soup

Every worker reads everything. Nobody knows which facts are load-bearing.

02Branch collision

Two agents touch the same checkout. The fastest path becomes conflict resolution.

03Confident drift

The diff is polished, but no one checks whether it solved the original problem.

+

The subagent loop

Click a phase.
See the handoff.

Delegation means moving one bounded task into a smaller context—not giving away responsibility.

+
What crosses contextsbrief → diff → evidence
PackageContainsWhy it matters
Briefgoal, files, boundariesstops the worker inventing the problem
Worktreebranch and isolated checkoutparallel edits do not collide
Checkstests, build, criteriaturns “looks good” into evidence
Diffsmall, reviewable changeintegration and discard stay cheap
+

Git worktrees

One branch
per hand.

A worktree is another directory linked to the same repository. Each agent gets its own checkout and index; history remains shared.

Select a node to inspect its checkout, owner, and next action.

repository topology 4 checkouts
+

Model routing

Do not pay for
reasoning where
you need rhythm.

Choose a job to see why the model profile changes.

WorkProfilePrompt shape
+
Model gearboxcapability tier × thinking effort

Two separate knobs

Choose the engine.
Then choose the gear.

A stronger model changes the capability ceiling. Higher reasoning effort gives that model more room to work. Start with the lightest combination that passes your real checks, then move one knob at a time.

REASONING / THINKING
ROUTING RULEUse strong models for ambiguity and judgment. Use lighter models for bounded execution. Raise effort only when evaluation shows a gain.
+

Skills

Write the right way
once.

A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.

01 / trigger clearly02 / load detail on demand03 / return evidence
SKILL PACKAGE
name: review-ui · check focus, mobile, reduced motion · run verification · return evidence
+
Create a skillrepeatable pain → reusable judgment

The skill forge

Teach the decision.
Keep the context light.

Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.

AFTER REAL USE
observe failure→sharpen one rule→retest behavior→keep it narrow
+
Common skillschoose behavior before model

The field kit

Different jobs.
Different instincts.

A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule and verified source.

ONE PRACTICAL LOADOUT
PLAN unlazy → BUILD ponytail-lite → DEBUG diagnosing-bugs → REPORT caveman
INSTALL PACKAsk your coding agent to verify, install, and validate the skills.
Review every source before installation. Existing local skills must be preserved.
+
Hands-on10 minutes / one missing feature

Tiny Tasks lab

Same task.
Better operating system.

Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.

Open the starter →Clone from Gitea →
Open the rules lab →Clone from Gitea →
THE MISSING FEATUREAdd All / Open / Done filters that survive reload and browser navigation.
STACK HTML · CSS · JavaScript DEPENDENCIES none FILES 3
RUN AGood prompt
Clear context · constraints · acceptance · evidence
RUN BGood prompt + skills
Same contract · explicit working methods · stronger proof
COMPARE THE RUNS
01 Files changed
02 New dependencies
03 Checks actually run
04 Evidence returned

+ +
Verificationrun each gate separately

Checks become evidence

Three layers.
Run each one alone.

Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.

01 · STATIC

Lint and types

Format, lint, type-check. Fast and scoped to one file. Run on every save.

pnpm lint; echo "lint=$?" +pnpm typecheck; echo "typecheck=$?"
02 · BEHAVIOR

Unit and contract

Tests that repeat. Run before claiming done.

pnpm test; echo "test=$?" +cd services/api && go test ./...
03 · INTEGRATION

Real UI and API

Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile overflow and a missing 404.

pnpm check:ui; echo "ui=$?" +TURBO_FORCE=true pnpm e2e
FOUR WAYS A GREEN REPORT IS FALSE
1
Pipe a gate

tail, grep, or head hide the real exit code — a pipeline returns the last command's status.

2
Swallow a rejection

A silent .catch(() => {}) hides a panic, an upstream limit, or a partial failure.

3
Trust the cache

Turbo caches results. A gate that "passes" may not have run — use TURBO_FORCE=true.

4
Skip the third layer

Lint and unit can both be green while the page breaks on mobile and the API never returns 404.

RUN IT YOURSELF · two labs, under 10 minutes each
Path A · verification lab

Fill the four-row comparison strip on the starter. Run A naively, Run B with $gate-discipline and $webapp-testing.

Open the starter →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starterPath B · rules lab

Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare diff size, gate invocations, and the names of checks the agent names back.

Open the rules lab →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules
+
Keep learning12 new readings + primary docs

Go deeper with official documentation, production case studies, Medium, and practitioner workflows. Rules and enforcement case study → Skills review desk → Primary references → 12-part reading path →

+
Navigate by ideashort chapters / one system

Prefer a focused chapter? Start with the route map, then jump directly to models, agents and worktrees, skill creation, rules, or the skills review desk.

+ diff --git a/index.html b/index.html index 32b9dd0..42934ea 100644 --- a/index.html +++ b/index.html @@ -1,36 +1,27 @@ - - - - - AI For Dummies — Field Guide - + + + + AI For Dummies — Start here + + - -
-
A field guide
review submissions ↗
/
AI ENGINEERING 01 / 2026
-

A presentation for humans who ship

AI for
dummies.

You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.

-
01strong model
for ambiguity
03bounded workers
in parallel
∞iterations
with evidence

Read this as a route map, not a prompt recipe.

-
RULE ZEROStrong model for ambiguity.
Light model for bounded work.
-
A small fleetcoordination before parallelism
ORCHESTRATOR

Decides what
needs to happen.

Opus / reasoning
→

The orchestrator preserves intent, writes small contracts, and gathers results that can be verified. It does not need to type every line.

-
Why the boundary mattersone vague task / three predictable failures
01Context soup

Every worker reads everything. Nobody knows which facts are load-bearing.

02Branch collision

Two agents touch the same checkout. The fastest path becomes conflict resolution.

03Confident drift

The diff is polished, but no one checks whether it solved the original problem.

-

The subagent loop

Click a phase.
See the handoff.

Delegation means moving one bounded task into a smaller context—not giving away responsibility.

-
What crosses contextsbrief → diff → evidence
PackageContainsWhy it matters
Briefgoal, files, boundariesstops the worker inventing the problem
Worktreebranch and isolated checkoutparallel edits do not collide
Checkstests, build, criteriaturns “looks good” into evidence
Diffsmall, reviewable changeintegration and discard stay cheap
-

Git worktrees

One branch
per hand.

A worktree is another directory linked to the same repository. Each agent gets its own checkout and index; history remains shared.

Select a node to inspect its checkout, owner, and next action.

repository topology 4 checkouts
-

Model routing

Do not pay for
reasoning where
you need rhythm.

Choose a job to see why the model profile changes.

WorkProfilePrompt shape
-
Model gearboxcapability tier × thinking effort

Two separate knobs

Choose the engine.
Then choose the gear.

A stronger model changes the capability ceiling. Higher reasoning effort gives that model more room to work. Start with the lightest combination that passes your real checks, then move one knob at a time.

REASONING / THINKING
ROUTING RULEUse strong models for ambiguity and judgment. Use lighter models for bounded execution. Raise effort only when evaluation shows a gain.
-

Skills

Write the right way
once.

A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.

01 / trigger clearly02 / load detail on demand03 / return evidence
SKILL PACKAGE
name: review-ui · check focus, mobile, reduced motion · run verification · return evidence
-
Create a skillrepeatable pain → reusable judgment

The skill forge

Teach the decision.
Keep the context light.

Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.

AFTER REAL USE
observe failure→sharpen one rule→retest behavior→keep it narrow
-
Common skillschoose behavior before model

The field kit

Different jobs.
Different instincts.

A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule and verified source.

ONE PRACTICAL LOADOUT
PLAN unlazy → BUILD ponytail-lite → DEBUG diagnosing-bugs → REPORT caveman
INSTALL PACKAsk your coding agent to verify, install, and validate the skills.
Review every source before installation. Existing local skills must be preserved.
-
Hands-on10 minutes / one missing feature

Tiny Tasks lab

Same task.
Better operating system.

Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.

Open the starter →Clone from Gitea →
Open the rules lab →Clone from Gitea →
THE MISSING FEATUREAdd All / Open / Done filters that survive reload and browser navigation.
STACK HTML · CSS · JavaScript DEPENDENCIES none FILES 3
RUN AGood prompt
Clear context · constraints · acceptance · evidence
RUN BGood prompt + skills
Same contract · explicit working methods · stronger proof
COMPARE THE RUNS
01 Files changed
02 New dependencies
03 Checks actually run
04 Evidence returned

- -
Verificationrun each gate separately

Checks become evidence

Three layers.
Run each one alone.

Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.

01 · STATIC

Lint and types

Format, lint, type-check. Fast and scoped to one file. Run on every save.

pnpm lint; echo "lint=$?" -pnpm typecheck; echo "typecheck=$?"
02 · BEHAVIOR

Unit and contract

Tests that repeat. Run before claiming done.

pnpm test; echo "test=$?" -cd services/api && go test ./...
03 · INTEGRATION

Real UI and API

Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile overflow and a missing 404.

pnpm check:ui; echo "ui=$?" -TURBO_FORCE=true pnpm e2e
FOUR WAYS A GREEN REPORT IS FALSE
1
Pipe a gate

tail, grep, or head hide the real exit code — a pipeline returns the last command's status.

2
Swallow a rejection

A silent .catch(() => {}) hides a panic, an upstream limit, or a partial failure.

3
Trust the cache

Turbo caches results. A gate that "passes" may not have run — use TURBO_FORCE=true.

4
Skip the third layer

Lint and unit can both be green while the page breaks on mobile and the API never returns 404.

RUN IT YOURSELF · two labs, under 10 minutes each
Path A · verification lab

Fill the four-row comparison strip on the starter. Run A naively, Run B with $gate-discipline and $webapp-testing.

Open the starter →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starterPath B · rules lab

Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare diff size, gate invocations, and the names of checks the agent names back.

Open the rules lab →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules
-
Keep learning12 new readings + primary docs

Go deeper with official documentation, production case studies, Medium, and practitioner workflows. Rules and enforcement case study → Skills review desk → Primary references → 12-part reading path →

-
Navigate by ideashort chapters / one system

Prefer a focused chapter? Start with the route map, then jump directly to models, agents and worktrees, skill creation, rules, or the skills review desk.

- +
+
AI FOR DUMMIES00 / START HEREreview desk ↗
+

The short route

Ship the
system.

Start with the map. Then open the one chapter that matches the decision in front of you: model, agent, worktree, skill, rule, or proof.

Take the full field guide →
+
+ + + + +
05

Hands-on

Compare a strong prompt with skill-enabled work.

Open lab →
+
06

Review desk

Browse original packages, references, scripts, and improvements.

Open desk →
+
+
THE THREADFrame uncertainty → isolate execution → preserve judgment → verify the change.
+
The route map is now the default entry. The full guide remains available whenever you want the whole narrative.
+
+ + diff --git a/landing.css b/landing.css new file mode 100644 index 0000000..0268466 --- /dev/null +++ b/landing.css @@ -0,0 +1 @@ +.guide-launch{display:inline-flex;gap:14px;align-items:center;margin-top:20px;padding:12px 16px;background:var(--ink);color:var(--paper);font:700 12px ui-monospace,monospace;letter-spacing:.06em;text-decoration:none;text-transform:uppercase;transition:transform .2s ease,background .2s ease}.guide-launch:hover{transform:translateY(-3px);background:var(--blue)}.guide-launch span{color:var(--gold);font-size:22px;line-height:0}.route-grid .card{display:flex;min-width:0;flex-direction:column}.route-grid .card a{margin-top:auto}.landing-note{display:grid;grid-template-columns:170px minmax(0,1fr);gap:30px;margin:0 0 70px;padding:25px 0;border-top:1px solid var(--ink);border-bottom:1px solid var(--ink)}.landing-note span{color:var(--red);font:700 11px ui-monospace,monospace;letter-spacing:.1em}.landing-note strong{font-size:clamp(22px,3.2vw,42px);line-height:1.08;letter-spacing:-.04em}@media(max-width:520px){.landing-note{grid-template-columns:1fr;gap:9px;margin-bottom:45px}}@media(prefers-reduced-motion:reduce){.guide-launch{transition:none}.guide-launch:hover{transform:none}} diff --git a/models/index.html b/models/index.html index de64d5c..e6ba8fc 100644 --- a/models/index.html +++ b/models/index.html @@ -1 +1 @@ -AI For Dummies — Models
← ROUTE MAP01 / MODELSfield guide ↗

Model routing

Choose the
engine.

A model has a capability ceiling. Effort controls how much room it gets to reason. Route by uncertainty and verification cost.

LOW

Bounded rhythm

Lookup, small edits, formatting, and transformations with clear checks.

MEDIUM

Default work

Normal implementation where the contract is clear but context matters.

HIGH

Ambiguity

Planning, architecture, security judgment, and hard failures.

Two knobs

Capability
× effort

ROUTING RULEstrong model + high effort → frame ambiguity · light model + low effort → bounded execution · raise one knob at a time → compare evidence

Sequence

Spend judgment
where it compounds.

01
PlanStrong model: scope, risks, acceptance, and worktree split.
02
BuildFocused worker: smallest context and lightest model that can pass.
03
ReviewIndependent pass when missed issues cost more than the call.
+AI For Dummies — Models
← ROUTE MAP01 / MODELSfield guide ↗

Model routing

Choose the
engine.

A model has a capability ceiling. Effort controls how much room it gets to reason. Route by uncertainty and verification cost.

LOW

Bounded rhythm

Lookup, small edits, formatting, and transformations with clear checks.

MEDIUM

Default work

Normal implementation where the contract is clear but context matters.

HIGH

Ambiguity

Planning, architecture, security judgment, and hard failures.

Two knobs

Capability
× effort

ROUTING RULEstrong model + high effort → frame ambiguity · light model + low effort → bounded execution · raise one knob at a time → compare evidence

Sequence

Spend judgment
where it compounds.

01
PlanStrong model: scope, risks, acceptance, and worktree split.
02
BuildFocused worker: smallest context and lightest model that can pass.
03
ReviewIndependent pass when missed issues cost more than the call.
diff --git a/scripts/audit-ui.mjs b/scripts/audit-ui.mjs new file mode 100644 index 0000000..f557102 --- /dev/null +++ b/scripts/audit-ui.mjs @@ -0,0 +1,18 @@ +import { readFileSync } from 'node:fs'; + +const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), 'utf8'); +const pages = ['index.html','full-guide/index.html','summary/index.html','models/index.html','agents/index.html','skills/index.html','rules/index.html','skills-review/index.html','hands-on/starter/index.html','hands-on/rules/index.html']; +for (const page of pages) { + const html = read(page); + if (!html.includes('name="viewport"')) throw new Error(`${page} lacks a viewport declaration`); + if (html.match(/<(script|link)[^>]+(src|href)="https?:[^\"]+"/i)) throw new Error(`${page} has an external runtime dependency`); +} +const shared = read('chapters.css'); +const skills = read('skills/styles.css'); +const guide = read('full-guide/index.html'); +const guideAudit = read('full-guide/audit.css'); +for (const token of ['@media(max-width:800px)','@media(max-width:520px)']) if (!shared.includes(token)) throw new Error(`shared chapter CSS lacks ${token}`); +for (const token of ['minmax(0,1.3fr)','overflow-wrap:anywhere','@media(max-width:800px)','prefers-reduced-motion']) if (!skills.includes(token)) throw new Error(`skills package CSS lacks ${token}`); +if (!guide.includes('href="audit.css"')) throw new Error('full guide does not load its responsive audit overrides'); +for (const token of ['.handoff table','.route-table button','overflow-wrap:anywhere']) if (!guideAudit.includes(token)) throw new Error(`full guide audit CSS lacks ${token}`); +console.log('responsive UI audit passed'); diff --git a/scripts/verify.mjs b/scripts/verify.mjs index 121bdf3..11fdea4 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -1,6 +1,7 @@ import { readFileSync } from 'node:fs'; const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), 'utf8'); -const html = read('index.html'); +const landingHtml = read('index.html'); +const html = read('full-guide/index.html'); const js = read('app.js'); const refs = read('docs/references/README.md'); const additional = read('docs/references/additional-reading.md'); @@ -38,9 +39,9 @@ console.log('rules content verification passed'); for (const token of ['const languageCopy','const stages','const skills','const prompts','renderStage','renderSkill','renderLanguage','copyPrompt','addEventListener']) if (!rulesJs.includes(token)) throw new Error(`missing rules interaction ${token}`); for (const token of ['data-lang="en"','data-lang="pt"','data-copy-prompt','aria-live="polite"','role="tablist"']) if (!rulesHtml.includes(token)) throw new Error(`missing rules control ${token}`); console.log('rules interaction verification passed'); -if (!html.includes('href="rules/"')) throw new Error('main presentation does not link to rules page'); -if (!html.includes('href="skills-review/"')) throw new Error('main presentation does not link to skills review page'); -for (const token of ['summary/','models/','agents/','skills/','chapter-route']) if (!html.includes(token)) throw new Error(`main presentation missing chapter route ${token}`); +if (!html.includes('href="../rules/"')) throw new Error('main presentation does not link to rules page'); +if (!html.includes('href="../skills-review/"')) throw new Error('main presentation does not link to skills review page'); +for (const token of ['../summary/','../models/','../agents/','../skills/','chapter-route']) if (!html.includes(token)) throw new Error(`main presentation missing chapter route ${token}`); if (rulesHtml.includes('script src="http') || rulesHtml.includes('rel="stylesheet" href="http')) throw new Error('rules page has an external runtime dependency'); for (const token of ['@media(min-width:2200px)','@media(max-width:900px)','@media(max-width:600px)','prefers-reduced-motion']) if (!rulesCss.includes(token)) throw new Error(`missing rules responsive contract ${token}`); console.log('rules standalone verification passed'); @@ -53,3 +54,13 @@ console.log('skills review verification passed'); for (const page of [summaryHtml, modelsHtml, agentsHtml, skillsHtml]) if (!page.includes('../chapters.css') || !page.includes('ROUTE MAP')) throw new Error('chapter page missing shared navigation'); for (const token of ['--ink','@media(max-width:800px)','@media(max-width:520px)']) if (!chaptersCss.includes(token)) throw new Error(`missing chapter responsive contract ${token}`); console.log('chapter route verification passed'); +for (const token of ['The short route','full-guide/','models/','agents/','skills/','rules/','hands-on/starter/','skills-review/']) if (!landingHtml.includes(token)) throw new Error(`landing page missing ${token}`); +if (landingHtml.includes('app.js')) throw new Error('landing page should remain a fast, static route map'); +console.log('landing route verification passed'); +for (const token of ['data-package-file="skill"','data-package-file="references"','data-package-file="scripts"','data-package-file="assets"','id="package-preview"','script src="app.js"']) if (!skillsHtml.includes(token)) throw new Error(`skills anatomy missing ${token}`); +const skillsApp = read('skills/app.js'); +const skillsCss = read('skills/styles.css'); +for (const token of ['const packageFiles','function renderPackage','addEventListener','renderPackage(\'skill\')']) if (!skillsApp.includes(token)) throw new Error(`skills anatomy interaction missing ${token}`); +for (const token of ['grid-template-columns:minmax(190px','overflow-wrap:anywhere','@media(max-width:800px)','prefers-reduced-motion']) if (!skillsCss.includes(token)) throw new Error(`skills anatomy responsive contract missing ${token}`); +console.log('skills anatomy verification passed'); +console.log('presentation verification passed'); diff --git a/skills/app.js b/skills/app.js new file mode 100644 index 0000000..882cd2c --- /dev/null +++ b/skills/app.js @@ -0,0 +1,23 @@ +const packageFiles = { + skill: { label: 'SKILL.md', title: 'The operating contract', body: 'The one file that should always be loaded. Define the exact trigger, the ordered workflow, safety limits, and the evidence the agent returns.', code: '---\nname: review-ui\ndescription: Review a changed UI for focus, reflow, and motion.\n---\n\n1. Inspect the changed interaction.\n2. Run the UI checks.\n3. Return findings with evidence.' }, + references: { label: 'references/', title: 'Facts, only when needed', body: 'Keep conditional detail out of the main instruction. A dialog pattern, framework caveat, or accessibility checklist belongs here when it is not needed for every review.', code: 'references/\n└── accessibility.md\n ├── keyboard interaction patterns\n └── focus and reflow checklist' }, + scripts: { label: 'scripts/', title: 'Mechanics that should not depend on memory', body: 'Turn deterministic checks into runnable tools. The agent still judges the result, but it should not have to recreate a viewport test or filename rule by hand.', code: 'scripts/\n└── check-reflow.mjs\n └── checks 320px, 1280px, and 4K widths' }, + assets: { label: 'assets/', title: 'Starting material, not hidden instructions', body: 'Use assets for templates and examples a person or agent can copy. Keep them clearly named so package readers can choose the right starting point.', code: 'assets/\n├── review-report.md\n└── focus-test-fixture.html' } +}; + +const preview = document.querySelector('#package-preview'); +const buttons = [...document.querySelectorAll('[data-package-file]')]; +function renderPackage(file) { + const item = packageFiles[file]; + preview.classList.remove('is-swapping'); + void preview.offsetWidth; + preview.classList.add('is-swapping'); + preview.innerHTML = `SELECTED / ${item.label}

${item.title}

${item.body}

${item.code}
`; + buttons.forEach((button) => { + const selected = button.dataset.packageFile === file; + button.classList.toggle('active', selected); + button.setAttribute('aria-selected', String(selected)); + }); +} +buttons.forEach((button) => button.addEventListener('click', () => renderPackage(button.dataset.packageFile))); +renderPackage('skill'); diff --git a/skills/index.html b/skills/index.html index 4418bd9..cda52ac 100644 --- a/skills/index.html +++ b/skills/index.html @@ -1 +1,33 @@ -AI For Dummies — Skills
← ROUTE MAP03 / SKILLSreview desk ↗

Reusable judgment

Teach the
decision.

A skill changes behavior. Keep the trigger precise, put the workflow in SKILL.md, and move conditional facts, scripts, and examples into focused files.

Package anatomy

One job.
More than
one file.

REVIEW-UI / SKILL PACKAGE├── SKILL.md → trigger + workflow · ├── references/ → conditional facts · ├── scripts/ → deterministic checks · └── assets/ → templates + examples

Create a skill

Observe →
trigger →
validate

01
Observe frictionFind a repeated decision or failure.
02
Define the triggerSay when it should load and when it should stay out.
03
Choose anatomyUse references for facts and scripts for deterministic mechanics.
04
Evaluate behaviorTest realistic prompts, edge cases, safety, and evidence.
+ + + + + + + AI For Dummies — Skills + + + + +
+
← ROUTE MAP03 / SKILLSreview desk ↗
+

Reusable judgment

Teach the
decision.

A skill changes behavior. Keep the trigger precise, put the workflow in SKILL.md, and move conditional facts, scripts, and examples into focused files.

+
+

Package anatomy

One job.
More than
one file.

Choose a file to see why it belongs in the package.

+
+
+

REVIEW-UI / SKILL PACKAGE

+ + + + +
+
+
+
+

Create a skill

Observe →
trigger →
validate

01
Observe frictionFind a repeated decision or failure.
02
Define the triggerSay when it should load and when it should stay out.
03
Choose anatomyUse references for facts and scripts for deterministic mechanics.
04
Evaluate behaviorTest realistic prompts, edge cases, safety, and evidence.
+ +
+ + + diff --git a/skills/styles.css b/skills/styles.css new file mode 100644 index 0000000..c1ec4c2 --- /dev/null +++ b/skills/styles.css @@ -0,0 +1 @@ +.top > *{min-width:0}.top a{overflow-wrap:anywhere}.package-hint{max-width:27ch;color:var(--muted)}.package-workbench{display:grid;grid-template-columns:minmax(190px,.85fr) minmax(0,1.3fr);min-width:0;background:var(--ink);border:1px solid var(--ink);box-shadow:10px 10px 0 color-mix(in srgb,var(--gold) 55%,transparent)}.package-tree{padding:22px 16px;border-right:1px solid #426070;min-width:0}.package-tree>p,.package-preview>span{margin:0 0 14px;color:var(--gold);font:700 11px/1.35 ui-monospace,monospace;letter-spacing:.1em}.package-tree button{display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:center;gap:8px;width:100%;padding:12px 8px;border:0;border-left:2px solid transparent;background:transparent;color:#d6e1e4;text-align:left;cursor:pointer;transition:background .2s ease,border-color .2s ease,transform .2s ease}.package-tree button:hover,.package-tree button:focus-visible,.package-tree button.active{border-left-color:var(--gold);background:#1f3a4b;outline:0}.package-tree button:hover{transform:translateX(3px)}.package-tree code{min-width:0;overflow-wrap:anywhere;font:700 13px/1.4 ui-monospace,monospace}.package-tree small{color:#aebfc7;font:11px/1.25 Arial,sans-serif;text-align:right}.package-preview{min-width:0;padding:26px;background:#173245;color:var(--paper)}.package-preview h3{margin:0 0 8px;font-size:clamp(24px,3vw,38px);line-height:1.02;letter-spacing:-.045em}.package-preview p{max-width:52ch;margin:0;color:#d6e1e4}.package-preview pre{max-width:100%;margin:20px 0 0;padding:15px;overflow:auto;border:1px solid #466274;background:#102837;color:#d6e1e4;font:12px/1.55 ui-monospace,monospace}.package-preview.is-swapping{animation:package-preview-in .34s ease both}@keyframes package-preview-in{from{opacity:.25;transform:translateY(7px)}to{opacity:1;transform:translateY(0)}}.links a{transition:background .2s ease,color .2s ease,transform .2s ease}.links a:hover{transform:translateY(-2px)}@media(max-width:800px){.package-workbench{grid-template-columns:1fr}.package-tree{border-right:0;border-bottom:1px solid #426070}.package-preview{padding:22px}}@media(max-width:520px){.top{gap:12px}.top a{font-size:10px}.package-tree{padding:18px 10px}.package-tree button{padding:12px 6px}.package-tree small{display:none}.package-preview{padding:18px}.package-preview pre{font-size:11px}}@media(prefers-reduced-motion:reduce){*,*::before,*::after{scroll-behavior:auto!important;animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}} diff --git a/summary/index.html b/summary/index.html index a1184ec..ed706a8 100644 --- a/summary/index.html +++ b/summary/index.html @@ -1 +1 @@ -AI For Dummies — Route map
← AI FOR DUMMIES00 / ROUTE MAPreview desk ↗

Start here

Ship the
system.

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.

05

Practice

Compare prompts and skill-enabled runs.

Open lab →
06

Review desk

Browse original files and improved drafts.

Open desk →
Each chapter stands alone; the order follows a real task becoming a reliable change.
+AI For Dummies — Route map
← AI FOR DUMMIES00 / ROUTE MAPreview desk ↗

Start here

Ship the
system.

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.

05

Practice

Compare prompts and skill-enabled runs.

Open lab →
06

Review desk

Browse original files and improved drafts.

Open desk →