Files

T

Marcos Paulo e2bcfff5ab feat: add reader vote widget and vote-service

The skills-review desk is static, so "which draft would you ship?" needs a
stateful counterpart. vote-service is a small Go API on its own pod backed by
a JSON file on a ReadWriteOnce PVC, with one active vote per skill per source
IP as the anti-abuse rule and CORS (ALLOWED_ORIGIN) as the caller boundary.

Deployment notes that differ from the obvious path, all confirmed against the
live cluster: the image is side-loaded with `ctr image import` plus
`imagePullPolicy: Never` because kubelet has no credentials for the Nexus ref;
the pod is pinned to `kubernets` because the hostpath PV takes a nodeAffinity
for whichever node first binds it; and public exposure is Caddy on the VPS,
not the cloudflared tunnel.

The ingress controller runs with `use-forwarded-headers` off, so nginx
overwrites X-Forwarded-For with its own peer — every visitor would collapse
into one voter and each skill would cap at one vote overall. Caddy stamps the
true remote address into X-Client-IP, which nginx forwards untouched, and
clientIP() reads that first. Scoped to this app rather than flipping the
global flag, which would change client-IP handling for every other ingress.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-04 23:49:55 +00:00

4.5 KiB

Raw Permalink Blame History

AI For Dummies

A lightweight, presentation-style field guide to AI-assisted engineering.

It explains how to combine a strong planning/review model with faster workers, reusable skills, subagent handoffs, Git worktrees, and explicit verification. An interactive field kit compares common behavior skills such as ponytail-lite, caveman, unlazy, research, debugging, and review. The skill-forge workflow covers discovery, triggers, package anatomy, progressive instructions, structural validation, and behavioral iteration. The hands-on lab provides a tiny starter project and copy-ready baseline and skill-enabled prompts for a short side-by-side exercise. An interactive model gearbox separates capability tier from reasoning effort across OpenAI, Claude, and Gemini, and every featured skill links to a pinned source with an approval-first installation prompt.

Run locally

This is a dependency-free static site:

python3 -m http.server 4173

Then open http://localhost:4173.

Verify the content and interaction contracts with:

npm run verify

Project structure

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, plus an interactive package anatomy explorer
skills-review/ — static review desk for submitted skills; its reader vote widget calls the separate vote-service
vote-service/ — small Go API + Kubernetes manifests backing the skills-review vote widget (see vote-service/README.md)
GATES.md — acceptance ledger for the project

Publishing

The Gitea instance has a Pages Server configured to publish a repository’s pages branch under pages.marcospaulo.dev.br. The intended site address is:

https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/

If the URL is not available yet, verify that the pages branch exists and that 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.

Reader voting on the skills-review desk

skills-review/ is static, so its "which draft would you ship?" vote widget calls a separate stateful service — vote-service/, a small Go API on its own pod, one vote per visitor enforced server-side by IP (a MAC address is never visible to a server across the internet, so it cannot be used). See vote-service/README.md for the API, the anti-abuse design, and the build/push/deploy steps; skills-review/index.html sets window.SKILLS_REVIEW_VOTE_API to point at it once deployed.

Research

See docs/references/README.md for official Claude, Codex, and Git documentation. The additional reading path bundles 12 verified articles and guides, including Medium and practitioner sources. See model routing for current provider controls and verified skill sources for commit-pinned provenance.

Rules and enforcement case study

Open /rules/ for a concise walkthrough grounded in the netcracker/interview repository. It shows how AGENTS.md, project-local skills, machine-readable repo ledgers, a UI contract ratchet, lint-staged, Husky, commitlint, specialist verifier agents, and PR review reinforce one another. Every example links to its source file in Gitea, and the page includes a copy-ready prompt for mapping the same layers in another repository.

The implementation patterns are also packaged as project-local skills in skills/. Use editorial-playbook when adding chapters or sections, and rules-case-study when turning repository controls into a source-linked teaching page.

4.5 KiB Raw Permalink Blame History Unescape Escape