Marcos Paulo
9015e7bd1d
Removes the Go source, Dockerfile, go.mod, and Kubernetes manifests. The
deployed service is untouched and the review desk still calls it over
window.SKILLS_REVIEW_VOTE_API; only the source leaves.
The runbook does not leave. vote-service/README.md moves to
docs/vote-service.md, because it carries the parts that are hard to
rediscover: why the ingress overwrites X-Forwarded-For and Caddy stamps
X-Client-IP instead, why the image is side-loaded into containerd rather
than pulled, and why the PVC pins the Deployment to one node.
This drops verify.mjs from 84 assertions to 83. The removed one read
vote-service/main.go for X-Forwarded-For and 'one active vote per skill'
-- the review desk's only anti-abuse control -- and there is no file left
to read. It is the first assertion this repository has ever lost.
Rather than lower the gate's floor and leave a bare number behind,
gate.sh now subtracts the number of entries in
.agents/context/assertion-removals.md from the baseline. A removal costs
a written reason in a tracked file, in the same commit, as a visible
diff. Tested at 82 assertions: still refused.
Also drops the 22 MB of PNG baselines under .agents/snapshots/before/ and
before-reduced-motion/. They pictured the hand-written site, which no
longer exists; visual-regression.mjs has no compare mode to diff them
against; and they are recoverable from d88d8b8.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
# Context: architecture
|
|
|
|
## Current (Astro, static output)
|
|
|
|
Ten routes, one `src/pages/` entry each, built to `dist/`:
|
|
|
|
| Route | Page | Islands |
|
|
| -------------------- | ------------------------------- | ----------------------------------------------- |
|
|
| `/` | `src/pages/index.astro` | — |
|
|
| `/full-guide/` | `src/pages/full-guide.astro` | `GuideSelector`, `LanguageToggle`, `CopyPrompt` |
|
|
| `/summary/` | `src/pages/summary.astro` | — |
|
|
| `/models/` | `src/pages/models.astro` | — |
|
|
| `/agents/` | `src/pages/agents.astro` | — |
|
|
| `/skills/` | `src/pages/skills.astro` | `SkillPackageExplorer` |
|
|
| `/rules/` | `src/pages/rules.astro` | `RulesInteractive` |
|
|
| `/skills-review/` | `src/pages/skills-review.astro` | `legacy/skills-review/app.js` |
|
|
| `/hands-on/starter/` | `public/` lab fixture | own |
|
|
| `/hands-on/rules/` | `public/` lab fixture | own |
|
|
|
|
## What is still unmigrated
|
|
|
|
`legacy/` holds the parts the migration did not componentize. They are not dead
|
|
files — the pages listed above import them, and the build fails without them.
|
|
|
|
- **`legacy/styles/guide.css`** (was `styles.css`) — the editorial visual
|
|
system, imported by `full-guide.astro`.
|
|
- **`legacy/styles/audit.css`** (was `full-guide/audit.css`) — responsive audit
|
|
overrides, imported by `full-guide.astro`.
|
|
- **`legacy/styles/chapters.css`** — imported by `ChapterLayout.astro`.
|
|
- **`legacy/styles/skills.css`**, **`skills-review.css`**, **`change-lens.css`**
|
|
— imported by their respective pages.
|
|
- **`legacy/skills-review/`** — `app.js` and the module graph under it
|
|
(`catalog.js`, `submitted-catalog.js`, `files.js`, `submitted-files.js`,
|
|
`vote.js`). `catalog.js` + `submitted-catalog.js` are the review desk's real
|
|
data model, 24 entries; they are a content collection in all but name.
|
|
|
|
These sit outside `src/` deliberately: `check-tokens.mjs` sweeps `src`, and
|
|
these files are full of raw hex and unnamed breakpoints. Moving one into `src/`
|
|
means migrating it to tokens in the same change, not adding an exclusion.
|
|
|
|
`responsive.css`, `landing.css`, `app.js`, `rules/app.js`, `rules/styles.css`,
|
|
and `skills/app.js` were deleted at cutover: their content lives in components.
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
content/ catalog entries, chapter copy, EN/PT strings (typed collections)
|
|
layouts/ BaseLayout, ChapterLayout, GuideLayout
|
|
components/ .astro by default; islands only where marked
|
|
styles/ tokens.css, base.css, then per-component styles
|
|
pages/ routes mirroring today's URLs exactly
|
|
public/
|
|
hands-on/ lab fixtures copied verbatim, never processed
|
|
```
|
|
|
|
### Non-negotiables
|
|
|
|
- **URLs do not change.** `/full-guide/`, `/skills-review/`,
|
|
`/hands-on/starter/` and the rest must resolve exactly as they do now,
|
|
trailing slash included. Existing links (including `docs/`, SilverBullet, and
|
|
shared URLs with `?author=…&skill=…&view=…` query params) must keep working.
|
|
- **Zero JS by default.** Seven of the ten pages ship no JavaScript. They must
|
|
still ship none. Islands are opt-in, per component, and justified.
|
|
- **`hands-on/` stays vanilla.** It lives in `public/` untouched. It is a lab
|
|
fixture, not a component.
|
|
- **No external runtime requests.** `audit-ui.mjs` enforces this and it is part
|
|
of the site's thesis. Self-host anything you add.
|
|
- **The review desk's query-param deep links keep working** — `?author=`,
|
|
`?skill=`, `?view=`, `?file=`, `?compare=`, `?render=`. They are documented in
|
|
the page footer and shared externally.
|
|
|
|
## Companion service
|
|
|
|
The vote API is a Go service on its own Kubernetes deploy cycle, reached by the
|
|
review desk over `window.SKILLS_REVIEW_VOTE_API`. Its source left this
|
|
repository on 2026-09-06; the deployed service is unchanged, and the review desk
|
|
still calls it. Keep the global, or replace it with a build-time
|
|
`PUBLIC_VOTE_API` env var — but if you do, update the service's own README in
|
|
the same change.
|
|
|
|
Its one-vote-per-IP assertion left `verify.mjs` with it. See
|
|
[`assertion-removals.md`](assertion-removals.md).
|