docs: add presentation operations guide

2026-09-02 13:51:08 +00:00
parent 6c591eac07
commit ada9b3aa19
2 changed files with 363 additions and 0 deletions
@@ -32,6 +32,7 @@ npm run verify
 - `app.js` — bilingual workflow, repository-tree, routing, and skill 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
 - `GATES.md` — acceptance ledger for the project
 ## Publishing
@@ -46,6 +47,9 @@ the repository’s `pages` branch exists. Gitea itself does not
 provide a built-in Pages server; this setup uses the instance’s separate Pages
 Server and Actions deployment path.
 For the complete authoring, verification, publication, rollback, worktree, and
 skill workflow, see [docs/operations-guide.md](docs/operations-guide.md).
 ## Research
 See [docs/references/README.md](docs/references/README.md) for official Claude,
@@ -0,0 +1,359 @@
 ---
 name: Guides/AI For Dummies Presentation
 tags:
  - guide
  - ai
  - skills
  - agents
  - worktrees
  - gitea
  - pages
 ---
 # AI For Dummies — authoring and operations guide
 This guide explains how to maintain the **AI For Dummies** presentation, how
 Gitea Pages is updated, and how the skills, subagents, model routing, and Git
 worktree practices taught by the presentation fit together.
 ## Quick links
 | Resource | Location |
 | :--- | :--- |
 | Live presentation | [https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/](https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/) |
 | Gitea repository | [https://git.marcospaulo.dev.br/netcracker/ai-for-dummies](https://git.marcospaulo.dev.br/netcracker/ai-for-dummies) |
 | Local checkout | `/home/marcos/Projects/ai-for-dummies` |
 | Source branch | `main` |
 | Published branch | `pages` |
 | Local verification | `npm run verify` |
 | SilverBullet page | `Guides/AI For Dummies Presentation` |
 ## How the site is built
 The presentation is deliberately dependency-free. Gitea Pages serves the
 repository files directly; there is no bundler or generated `dist/` folder.
 | File | Responsibility |
 | :--- | :--- |
 | `index.html` | Semantic sections, 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 |
 | `scripts/verify.mjs` | Content and interaction contract checks |
 | `docs/references/` | Primary documentation and additional reading |
 The English HTML is the fallback when JavaScript is unavailable. Portuguese
 copy is applied by `app.js`; the language preference is stored in
 `localStorage`, and the document language changes to `pt-BR`.
 ## Normal edit and publish workflow
 ```mermaid
 flowchart LR
  E[Edit main] --> V[npm run verify]
  V --> C[Commit]
  C --> M[Push main]
  M --> P[Fast-forward pages]
  P --> S[Gitea Pages Server]
  S --> L[Live URL]
 ```
 ### 1. Start from current `main`
 ```bash
 cd /home/marcos/Projects/ai-for-dummies
 git switch main
 git pull --ff-only
 git status --short --branch
 ```
 Do not overwrite unrelated local changes. The untracked
 `scripts/inspect.py` and `scripts/__pycache__/` are local visual-test artifacts
 and are intentionally not part of the published site.
 ### 2. Preview locally
 ```bash
 python3 -m http.server 4173
 ```
 Open [http://localhost:4173](http://localhost:4173). Check English and
 Portuguese, keyboard focus, the interactive panels, and at least one desktop
 and one mobile viewport.
 ### 3. Verify before committing
 ```bash
 npm run verify
 node --check app.js
 git diff --check
 ```
 Expected project verifier output:
 ```text
 content verification passed
 interaction verification passed
 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 commit -m "feat: describe the change"
 git push origin main
 ```
 Stage only files that belong to the change. Review `git status --short` before
 committing.
 ### 5. Fast-forward the published branch
 Use a temporary worktree so the current checkout stays on `main`:
 ```bash
 git worktree add /tmp/ai-for-dummies-pages pages
 git -C /tmp/ai-for-dummies-pages merge --ff-only main
 git -C /tmp/ai-for-dummies-pages push origin pages
 git worktree remove /tmp/ai-for-dummies-pages
 ```
 The `pages` branch should represent the exact published source. Avoid editing
 it directly and avoid force-pushing it.
 ### 6. Verify the deployment
 ```bash
 curl -I https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/
 ```
 If the edge still shows an older page, retry with the current commit as a
 cache-busting query:
 ```bash
 git rev-parse --short HEAD
 curl -I "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=COMMIT"
 ```
 The correct URL pattern is **owner subdomain + repository path**:
 ```text
 https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/
 ```
 `https://ai-for-dummies.netcracker.pages...` is the wrong hostname and can
 produce `ERR_SSL_PROTOCOL_ERROR` because it does not match the wildcard TLS
 certificate.
 ## Adding or changing a presentation section
 1. Add semantic HTML and stable `data-*` hooks in `index.html`.
 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
   relevant interaction data.
 5. Add responsive CSS, visible keyboard focus, and reduced-motion behavior.
 6. Extend `scripts/verify.mjs` with structural tokens that would disappear if
   the feature were accidentally removed.
 7. Test English, Portuguese, Full HD, 4K, and mobile layouts.
 Keep English as the source HTML. Do not duplicate the whole site into separate
 language endpoints unless the architecture changes to server-side routing.
 ## The agent workflow taught by the presentation
 ```mermaid
 flowchart TD
  H[Human intent and boundaries] --> O[Strong orchestrator]
  O --> B1[Bounded UI worker]
  O --> B2[Bounded test worker]
  O --> B3[Bounded docs worker]
  B1 --> R[Independent review]
  B2 --> R
  B3 --> R
  R --> E[Evidence and integration]
  E --> H
 ```
 Use a strong model where ambiguity dominates: repository inspection,
 architecture, decomposition, risk analysis, and review. Use faster or cheaper
 models for bounded implementation only after the brief defines the goal,
 files, constraints, and checks.
 Every worker should return:
 - changed files and a concise diff summary;
 - checks executed and their results;
 - remaining risk, uncertainty, or blocked work;
 - no unrelated edits.
 Parallelism helps only when tasks are genuinely independent. More agents add
 coordination cost, context cost, and integration risk.
 ## Worktree-per-worker model
 A Git branch isolates history; a Git worktree also isolates the active files
 and index. Give each editing agent one task, one branch, and one worktree.
 ```bash
 git worktree add ../task-ui -b agent/ui
 git worktree add ../task-tests -b agent/tests
 git worktree add ../task-docs -b agent/docs
 git worktree list
 ```
 Recommended lifecycle:
 1. Create the task branch and worktree.
 2. Give the worker a bounded brief and acceptance checks.
 3. Let the worker edit and verify only inside its worktree.
 4. Review `git diff main...agent/name` from fresh context.
 5. Merge, request changes, or discard.
 6. Remove the finished worktree with `git worktree remove PATH`.
 Worktrees prevent agents from changing the same checkout underneath each
 other. They do not eliminate semantic merge conflicts; task ownership and
 review still matter.
 ## What a skill is
 A skill is a reusable procedure that changes how an agent makes decisions. It
 is not magical memory and does not replace a task brief or acceptance criteria.
 ```text
 skill-name/
 ├── SKILL.md              required: name, description, workflow, constraints
 ├── agents/openai.yaml    optional: UI metadata and invocation policy
 ├── scripts/              optional: deterministic repeated operations
 ├── references/           optional: conditional facts and detailed guidance
 └── assets/               optional: templates or files copied into output
 ```
 Progressive disclosure keeps context light:
 1. **Name and description** are visible during selection.
 2. **SKILL.md** loads when the skill applies.
 3. **References, scripts, and assets** load only when the workflow needs them.
 Do not create empty resource directories. Every file should have a real
 consumer and should improve a decision or repeatable operation.
 ## Skill-creation workflow
 ### 1. Observe repeated friction
 Collect realistic requests. Identify a non-obvious decision that agents keep
 rediscovering or getting wrong. A one-off project fact usually belongs in
 project documentation, not a global skill.
 ### 2. Define discovery
 Choose a lowercase, action-oriented name. Write a concise description stating
 what the skill does and when it applies. Include a boundary only when it stops
 likely false activation.
 ```yaml
 ---
 name: review-ui
 description: Review frontend changes for focus, responsive layout, and reduced-motion behavior.
 ---
 ```
 ### 3. Choose the smallest anatomy
 - Put shared workflow and constraints in `SKILL.md`.
 - Add `scripts/` when deterministic execution prevents repeated reimplementation.
 - Add `references/` for details needed only in certain modes.
 - Add `assets/` for templates or generated-output inputs.
 - Add `agents/openai.yaml` only when UI metadata or invocation policy is useful.
 ### 4. Write decision-changing guidance
 Assume the agent is already capable. Include desired outcome, non-obvious
 constraints, routing decisions, stopping conditions, and evidence expectations.
 Remove generic advice, duplicated manuals, and speculative rules.
 ### 5. Validate and iterate
 ```bash
 python3 /home/marcos/.codex/skills/.system/skill-creator/scripts/quick_validate.py /path/to/skill
 ```
 Structural validation checks package shape and frontmatter. It does not prove
 the skill makes good decisions. Also run every new script and test realistic
 prompts. After real failures, sharpen the narrowest relevant rule instead of
 accumulating universal instructions.
 ## Common skills and when to use them
 | Skill | Use it for | Core rule | Avoid when |
 | :--- | :--- | :--- | :--- |
 | `ponytail-lite` | Requests inviting unnecessary frameworks or abstractions | Stop at the first sufficient solution: reuse, standard library, native platform, existing dependency, then minimum new code | Simplification would remove validation, security, accessibility, or real edge cases |
 | `caveman` | Routine status, handoffs, and technical summaries | Put signal first and remove filler | Security warnings, irreversible actions, or sequences where terse wording can be misread |
 | `unlazy` | Substantial builds, audits, and parallel work | Define observable gates and finish against evidence | Trivial edits or factual answers |
 | `research` | APIs, standards, current behavior, and architecture facts | Trace claims to primary sources and save cited findings | The answer is already stable and locally proven |
 | `diagnosing-bugs` | Hard bugs, flakes, and regressions | Build a fast red-capable feedback loop before theorizing | Simple known fixes with an existing regression test |
 | `code-review` | Branch or PR review | Check repository standards and original specification as separate axes | No comparison point or review request exists |
 | `token-saver` | Verbose tests, builds, logs, and Git output | Preserve signal and retain full failure output for recovery | Exact raw wording or full diff context is required |
 | `webapp-testing` | Frontend interaction and responsive verification | Drive the real UI and assert on DOM, console, and screenshots | Static structure checks are already decisive |
 Useful compositions:
 - **Large feature:** `unlazy` → `ponytail-lite` → implementation → `code-review`.
 - **Hard regression:** `diagnosing-bugs` → fix → `code-review` → `caveman` handoff.
 - **Documentation with unstable facts:** `research` → writing → cited verification.
 - **Interactive presentation:** `frontend-design` → `webapp-testing` → responsive evidence.
 ## Troubleshooting
 | Symptom | Check | Fix |
 | :--- | :--- | :--- |
 | Live page is old | Compare `main`, `pages`, and remote SHAs | Fast-forward and push `pages`; retry with `?v=COMMIT` |
 | `ERR_SSL_PROTOCOL_ERROR` | Confirm the hostname | Use `netcracker.pages.marcospaulo.dev.br/ai-for-dummies/` |
 | Portuguese copy is missing | Inspect `translations.pt` and dynamic interaction data | Add both static and dynamic translations; reload after clearing saved language if needed |
 | New control does nothing | Check `data-*` hook, event binding, and render function | Add the hook to `scripts/verify.mjs`; run `node --check app.js` |
 | Desktop works, mobile breaks | Inspect the section below 800 px and 600 px | Add an explicit stacking rule and preserve focus visibility |
 | Worktree creation says branch is checked out | Run `git worktree list` | Reuse or remove the existing worktree; do not force it |
 | Pages push is rejected | Fetch and inspect remote branch state | Reconcile normally; never force-push without an explicit recovery decision |
 ## Safe rollback
 Prefer a normal revert so history and the `pages` branch remain fast-forwardable:
 ```bash
 git switch main
 git revert BAD_COMMIT
 git push origin main
 git worktree add /tmp/ai-for-dummies-pages pages
 git -C /tmp/ai-for-dummies-pages merge --ff-only main
 git -C /tmp/ai-for-dummies-pages push origin pages
 git worktree remove /tmp/ai-for-dummies-pages
 ```
 Verify the live URL after rollback. Do not use `reset --hard` or force-push for
 ordinary content recovery.
 ## Completion checklist
 - [ ] English content is complete without JavaScript.
 - [ ] Portuguese static and dynamic copy is complete.
 - [ ] Mouse and keyboard interactions work.
 - [ ] Full HD, 4K, and mobile layouts remain readable.
 - [ ] `npm run verify`, `node --check app.js`, and `git diff --check` pass.
 - [ ] `main` is pushed.
 - [ ] `pages` fast-forwards to the same commit.
 - [ ] Live endpoint returns HTTP 200 and contains the new section.
 - [ ] Research links and this SilverBullet guide are updated when the workflow changes.
 ## Resumo rápido em português
 Edite sempre em `main`, rode as verificações, faça commit e push, depois avance
 `pages` por fast-forward usando um worktree temporário. O servidor externo do
 Gitea Pages publica diretamente essa branch. Use o endereço com
 `netcracker.pages.../ai-for-dummies/`; o formato inverso quebra o TLS.
 Para agentes: modelo forte planeja e revisa; workers delimitados implementam em
 worktrees separados; evidências voltam ao orquestrador. Para skills: capture
 uma decisão repetida, defina um gatilho preciso, crie apenas os recursos úteis,
 escreva orientação que muda decisões e valide estrutura **e** comportamento.