Marcos Paulo
580293867d
Deletes the pre-Astro pages, scripts, and stylesheets that the migration replaced, and moves the ones it did not replace out of the way. Deleted (32 files): app.js, responsive.css, landing.css, rules/app.js, rules/styles.css, skills/app.js, the ten route index.html files, and the root hands-on/ copy, which is byte-identical to public/hands-on/ -- the one the build actually ships. Moved to legacy/ (12 files): styles.css, full-guide/audit.css, chapters.css, skills/styles.css, skills-review/styles.css, skills-review/change-lens.css, and the skills-review/app.js module graph. These are not dead. The Astro pages import them and the build fails without them, which the plan had not accounted for. They go to legacy/ rather than src/ because check-tokens.mjs sweeps src, and these files are full of raw hex and unnamed breakpoints: moving one into src/ should mean migrating it to tokens in the same change, not adding a scan exclusion. The prettier, stylelint, and eslint ignore lists that already named these files at their old paths now name legacy/ instead. verify.mjs no longer reads app.js. The 102 Portuguese strings were extracted from its translations.pt object before deletion into .agents/snapshots/full-guide-pt.json -- a legacy capture, not a snapshot of the Astro build, so the assertion still compares against an independent source. The brace-matching helper's assertion is replaced by one that rejects an empty snapshot entry, without which trimming the snapshot would make the presence check pass vacuously. Count stays at 84. audit-ui.mjs reads the ten pages from dist/ and resolves Astro's base-absolute hrefs against it. Before deleting anything, rendered-text-diff was run across all ten routes plus both Portuguese pages: every one at parity, 0 missing and 0 extra. That comparison is not repeatable once the legacy files are gone. computed-style-diff on /full-guide/ stays at 32 differences, so the moves are style-neutral. Docs updated to match: README, AGENTS.md, GATES.md, the architecture context, the operations guide's lab instructions, and the three skills that told you to serve the vanilla site. Publishing is not part of this commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
79 lines
4.3 KiB
Markdown
79 lines
4.3 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
|
|
|
|
`vote-service/` is a Go API on its own Kubernetes deploy cycle, reached by the
|
|
review desk over `window.SKILLS_REVIEW_VOTE_API`. The refactor does not touch
|
|
it. Keep the global, or replace it with a build-time `PUBLIC_VOTE_API` env var —
|
|
but if you do, update `vote-service/README.md` in the same change.
|