Migrate totalcross.com from Gatsby to Astro

.agent/PLANS.md

@@ -0,0 +1,257 @@
+<!--
+SPDX-FileCopyrightText: 2026 Amalgam Solucoes em TI Ltda.
+SPDX-License-Identifier: MIT
+-->
+
+# Codex Execution Plans (ExecPlans)
+
+An ExecPlan is a living design and execution document for a complex feature,
+release-process change, platform addition, or significant refactor. It must let a
+new contributor make the next safe change, verify it proportionally, and recover
+after interruption without reconstructing the complete project history.
+
+## Precedence and scope
+
+Apply instructions in this order:
+
+1. safety and data-preservation instructions;
+2. explicit user instructions for the current task;
+3. the token, output, commit, and validation budget in `AGENTS.md`;
+4. this document;
+5. instructions specific to the active ExecPlan.
+
+An ExecPlan cannot make an expensive validation mandatory after every slice merely
+because it recorded that validation at an earlier checkpoint. Use the smallest
+validation that proves the current change unless the user requests more, the
+milestone is closing, an ABI/platform/release contract changed, or prior failure
+evidence justifies escalation.
+
+## Resumable plans, not duplicated context
+
+A plan is self-contained when it contains the knowledge needed to implement the
+change or names stable repository paths that hold that knowledge. A reference
+must explain what the file contains and when it should be read. “See the docs” is
+not sufficient.
+
+When creating a new plan, read `AGENTS.md` and this file in full, then inspect only
+the repository paths and external sources needed to make the plan concrete.
+
+When resuming a plan, read its state file first when one exists. Otherwise locate
+the active headings and read only the sections needed for the next action. Do not
+routinely reread the full plan, architecture documents, historical archive,
+evidence index, or editorial report. Context compaction is not a reason to search
+the whole repository again.
+
+The active plan should normally remain around 300–450 lines and a state file
+around 100–150 lines. These are soft limits. When a plan grows beyond them, move
+completed detail and raw evidence into supporting files rather than deleting
+necessary safety or implementation context.
+
+## Required plan structure
+
+Every active ExecPlan contains or adapts these sections:
+
+- `Purpose / Big Picture`: observable developer or user outcome.
+- `Working Set and Resume Protocol`: supporting-file paths and the first read for
+  continuation.
+- `Progress`: meaningful completed checkpoints and remaining work.
+- `Current Architecture and Scope`: only context needed for remaining work.
+- `Plan of Work`: completed milestone summaries, active milestone, and next
+  milestones.
+- `Surprises & Discoveries`: observations that materially affect remaining work.
+- `Decision Log`: choices that change architecture, compatibility, release,
+  validation, or operation policy.
+- `Validation and Acceptance`: observable behavior and applicable validation
+  levels from `AGENTS.md`.
+- `Risks and Open Questions`: unresolved issues that can change implementation.
+- `Idempotence and Recovery`: safe retry, concurrency, and local-change behavior.
+- `Outcomes & Retrospective`: short milestone-level factual summary.
+- `Revision Note`: only material plan-policy or milestone consolidations.
+
+A completed plan also has a factual editorial report. The active plan may point to
+`.agent/reports/<plan>-editorial.md` rather than carrying a large report inline.
+
+## Supporting files
+
+Use supporting files only when they simplify resumption:
+
+- `.agent/state/<plan>.md` is rewritten rather than appended. It records the
+  active milestone and slice, last logical commit, active paths, next concrete
+  action, focused validation completed, deferred validation and reason, active
+  decisions, blockers, deliberate out-of-scope files, and a resume command. It is
+  the first normal read.
+- `.agent/evidence/<plan>.md` or `.jsonl` is append-only. It records compact
+  evidence: timestamp, revision, milestone/slice, command or wrapper, status,
+  counts, log/artifact paths, necessary hashes, and limitation. Search it
+  selectively; do not read it during every resume.
+- `.agent/archive/<plan>-history.md` stores completed milestone detail, rejected
+  alternatives whose rationale remains useful, and retired revision notes. It is
+  not read by default.
+- `.agent/reports/<plan>-editorial.md` is a concise factual handoff updated at
+  important milestone completion and final completion, not after every slice.
+
+Do not copy the same log, matrix, hash, benchmark table, or conclusion into every
+supporting file.
+
+## Progress, decisions, and checkpoints
+
+`Progress` records meaningful checkpoints: a logical commit, functional slice,
+material direction change, or completed milestone. Do not add separate entries
+for implementation, validation, documentation, and commit when they belong to one
+checkpoint. Point to evidence rather than repeating it.
+
+The `Decision Log` contains only choices that alter future work. Do not record
+mechanical test commands, every target name, or standing repository policy.
+
+Keep `Surprises & Discoveries` only for observations that affect remaining work.
+Move resolved history to the archive.
+
+During a slice, update state only when needed for safe resumption. After a logical
+commit, record what changed, focused validation, remaining work, and deferrals.
+At a milestone checkpoint, consolidate the plan, history, evidence, editorial
+report, and next state.
+
+## Validation and benchmarks
+
+Validation is mandatory in proportion to risk. Use the four validation levels in
+`AGENTS.md` and stop at the first sufficient level.
+
+Each milestone must state observable acceptance and the validation level normally
+required. A plan may name exact focused commands but must not turn a historical
+full matrix into a perpetual slice requirement.
+
+Save complete tool output in logs or artifacts. Record compact summaries and paths
+in evidence.
+
+Benchmark only workloads that exercise the changed behavior or measurement path.
+Run a small smoke benchmark for an affected hot path and a full checkpoint only at
+milestone closure, optimization validation, measurement-regime change, or explicit
+user request. Preserve raw samples outside the active plan.
+
+## Writing guidance
+
+Use plain language. Define non-obvious terms at first use. State the observable
+purpose before implementation detail.
+
+Name repository-relative paths, modules, scripts, working directories, commands,
+expected concise outcomes, and safe retry behavior. Prefer prose to large tables
+and inventories.
+
+Do not replace key repository knowledge with an external link. Stable local
+documentation may be referenced when its role and read condition are stated.
+
+Do not dump generated code, full workflows, large manifests, raw logs, complete
+matrices, or every differential case into an ExecPlan. Use small excerpts, paths,
+commands, and evidence references.
+
+## Milestones
+
+A milestone describes:
+
+- the goal and why it matters;
+- the files and contracts changed;
+- the behavior that exists at its end;
+- the proof required;
+- fallback or compatibility paths that remain;
+- the next boundary.
+
+Milestones should produce incremental observable value. Prototypes and parallel
+paths are acceptable when they are bounded, additive, independently testable, and
+have clear promotion or removal criteria.
+
+## Releases and state-changing work
+
+A plan that creates commits, tags, pushes, releases, or metadata updates must state:
+
+- which operations are automatic and which require explicit user execution;
+- concurrency protection and race rechecks;
+- idempotent behavior when a release already exists;
+- how an effective release tag is selected;
+- which commit a tag and release point to;
+- how partial publication is detected and recovered;
+- how unrelated local changes remain untouched.
+
+Prefer dry-run or build-only validation before enabling release operations.
+
+## Completion
+
+At plan completion, reconcile the final implementation with `Outcomes &
+Retrospective` and the editorial report. Distinguish delivered work from planned
+work, measurements from estimates, and supported targets from aspirations.
+
+The editorial report should contain:
+
+- `Editorial Summary`;
+- `Original Plan versus Actual Outcome`;
+- `What Changed`;
+- `Decisions and Trade-offs`;
+- `Unexpected Problems and Discoveries`;
+- `Validation and Measurable Results`;
+- `Useful Evidence and Examples`;
+- `Limitations, Remaining Work, and Open Questions`;
+- `Possible Article Angles`;
+- `Suggested Narrative`;
+- `Claims Requiring Human Review`.
+
+## Minimal skeleton
+
+    # <Short action-oriented title>
+
+    This ExecPlan follows `AGENTS.md` and `.agent/PLANS.md`.
+
+    ## Purpose / Big Picture
+
+    Explain the observable outcome and how a developer can see it.
+
+    ## Working Set and Resume Protocol
+
+    Name state, evidence, history, and editorial paths and when each is read.
+
+    ## Progress
+
+    - [x] (YYYY-MM-DDThh:mm:ssZ) Significant completed checkpoint.
+    - [ ] Active slice and next concrete action.
+    - [ ] Remaining milestone or finalization work.
+
+    ## Current Architecture and Scope
+
+    Explain only the contracts and paths needed for remaining work.
+
+    ## Plan of Work
+
+    Summarize completed milestones, detail the active milestone, and describe next
+    milestones with observable acceptance.
+
+    ## Surprises & Discoveries
+
+    - Observation: ...
+      Evidence: ...
+
+    ## Decision Log
+
+    - Decision: ...
+      Rationale: ...
+      Date: ...
+
+    ## Validation and Acceptance
+
+    Name the validation level, focused command, expected concise result, and any
+    deferred expensive validation with its reason.
+
+    ## Risks and Open Questions
+
+    State unresolved implementation, platform, compatibility, release, or
+    concurrency questions.
+
+    ## Idempotence and Recovery
+
+    State safe retries, partial-release recovery, and local paths that remain
+    untouched.
+
+    ## Outcomes & Retrospective
+
+    Summarize completed milestone outcomes and point to evidence/history.
+
+    ## Revision Note
+
+    Record only a material plan-policy or milestone consolidation and its reason.

.agent/archive/astro-site-migration-history.md

@@ -0,0 +1,126 @@
+<!--
+SPDX-FileCopyrightText: 2026 Amalgam Solucoes em TI Ltda.
+SPDX-License-Identifier: MIT
+-->
+
+# Astro site migration history
+
+## M0A — Repository licensing and agent tooling prerequisite
+
+Completed 2026-08-10 at `a44ea2d`. The supporting plan installed the local planning
+contract, licensing policy and mappings, conservative validator/fixer, repository
+skills, project file headers, and a license CI gate while retaining the legacy
+Gatsby publication path. Its separate editorial report records policy limitations
+and human-review items.
+
+## M0 — Baseline and migration guardrails
+
+Completed 2026-08-10 from source checkpoint `c7182dc`. M0 recorded immutable source
+and deployment refs, current Pages configuration, 14 public routes, nine endpoints,
+42 source image assets, integrations, navigation/metadata behavior, live HTTP
+responses, and the recoverable legacy publication path. The Gatsby production build
+passed under the documented Rosetta Node 14/npm 6 compatibility environment with
+14/14 routes and 295 generated files.
+
+The in-app Browser limitation was replaced by the approved automated fallback.
+Headless Playwright captured eight deterministic desktop/mobile viewport baselines
+from the immutable deployed `master` artifact, and their dimensions and hashes are
+recorded beside the images. No production or remote repository settings changed in
+M0.
+
+## M1 — Astro foundation and visual system
+
+Completed 2026-08-10 after M0 closure. Astro 7.2.0 and TypeScript 6.0.3 now produce a
+static site for `https://totalcross.com` under supported Node 24. The implementation
+adds a typed base layout, canonical/social metadata, shared header/footer/button
+components, extracted design tokens, a responsive full home page, local font assets,
+and reused legacy artwork without React hydration.
+
+The Astro source remains temporarily isolated under `astro/`, with `static/` as its
+public directory and the legacy Gatsby images imported in place. This keeps the
+Gatsby recovery path operational and avoids duplicating large assets until route
+parity allows M7 to make the final conventional `src/`/`public/` move. The coexistence
+lockfile pins modern ESM `cookie` at the root because Gatsby otherwise hoisted an
+incompatible legacy release into Astro's prerender bundle.
+
+Astro check completed with zero diagnostics, the production build generated the home
+route without client script sources, and Playwright comparisons at 1440×900 and
+390×844 confirmed the shared shell/home identity against the M0 captures.
+
+## M2 — Public page and route parity
+
+Completed 2026-08-10. All 14 legacy HTML contracts now have Astro equivalents:
+home, both 404 forms, eight institutional pages, blog landing, the root-level Tecdet
+article, and the accidental Gatsby TypeScript starter route. Institutional content
+uses the shared shell and reusable hero/card/prose primitives. The contact form keeps
+its existing Getform POST endpoint, and the deployed manifest plus favicon/icon
+family were recovered byte-for-byte from immutable `master=6c82739`.
+
+A manifest-driven validator checks the M0 route list and every generated local
+`href`/`src`. Astro's single 404 route naturally emits `/404.html`; a small generated-
+output preparation step copies that document to `/404/index.html` to preserve the
+observed second URL without committing build output.
+
+Final validation reported zero Astro diagnostics, built 13 native routes plus the
+compatibility 404 copy, found all 14 legacy routes and zero broken local references,
+and passed desktop/mobile visual comparison for Why TotalCross, blog, and the Tecdet
+article. RSS, sitemap, typed blog collections, and richer article metadata remain
+deliberately assigned to M3.
+
+## M3 — Blog, SEO, feeds, and localization readiness
+
+Completed 2026-08-10. A typed Astro content layer now owns authors and Markdown/MDX
+articles, including dates, locale/translation identity, taxonomy, optional series,
+draft status, cover, preserved legacy URL, and opt-in cross-post intent. The Tecdet
+customer article moved into the collection without changing its root-level URL or
+third-party license mapping. Paired English/Portuguese draft fixtures exercise the
+authoring schema but are excluded from every production surface.
+
+The blog landing, article, author, tag, and category pages are collection-driven.
+The article layout adds heading navigation, code/media/table support, optional
+translation and series links, article metadata, and JSON-LD. RSS and an Astro sitemap
+chain are generated, with `/sitemap.xml` retained as a compatibility entry point.
+
+Final Node 24 validation completed with zero Astro diagnostics, 18 native pages,
+20 prepared HTML documents, all 14 legacy route contracts, zero broken references,
+and passing focused assertions for archives, feeds, sitemaps, canonical metadata,
+JSON-LD, draft exclusion, and translation pairing. Repository license tests passed
+6/6; the path policy now recognizes editorial content in legacy, coexistence, and
+final Astro source locations.
+
+## M6 — Optional cross-posting
+
+Completed 2026-08-10 before deployment cutover so the article metadata contract is
+stable. Distribution is disabled by default and isolated in a manual workflow whose
+inputs select article, DEV/Medium, draft/publish intent, and dry run. The dependency-
+free CLI also has an automatic mode that refuses any destination not enabled in the
+article's `crossPost` metadata.
+
+The Forem v1 adapter verifies canonical deployment before a live request, searches
+the authenticated account's published and draft articles by TotalCross canonical
+URL, and updates a match rather than creating a duplicate. DEV credentials are only
+needed for live writes. Medium uses its supported URL import/manual editor and
+canonical-link flow; no legacy Medium API dependency exists.
+
+Six unit tests and three CLI dry runs passed without credentials or network writes.
+They prove default-off behavior, opted-in canonical DEV payloads, create/update
+idempotency, workflow isolation from Pages, and Medium manual preparation. No live
+external article was created merely for validation.
+
+## M4 — Versioning, changelog, and release metadata
+
+Completed 2026-08-10. The private package is now `totalcross-site@1.0.0` with the
+real production homepage, TotalCross GitHub repository and issue tracker, and the
+Astro-supported Node floor. The old 0.1.0 value and Gatsby starter identity were not
+intentional releases.
+
+The initial Keep-a-Changelog document records notable platform, URL/navigation, blog,
+distribution, and validation changes under Unreleased. Release guidance defines site
+SemVer, excludes ordinary article edits from software releases, requires a clean and
+revalidated production source commit, and permits only an annotated tag followed by
+an optional matching GitHub Release.
+
+The dry-run consistency checker passed for package/lockfile version identity,
+changelog state, release procedure, and tag semantics. Read-only local and remote
+queries confirmed that `v1.0.0` does not yet exist. Tag creation remains deliberately
+deferred until the final production artifact is proven in M7.