Skip to content

docs+core: close the remaining recipe → Pattern rename gaps#1072

Merged
zachshallbetter merged 1 commit into
mainfrom
docs/pattern-rename-remaining-gaps
Jul 13, 2026
Merged

docs+core: close the remaining recipe → Pattern rename gaps#1072
zachshallbetter merged 1 commit into
mainfrom
docs/pattern-rename-remaining-gaps

Conversation

@zachshallbetter

Copy link
Copy Markdown
Owner

A second, deeper pass beyond phases 0–4: apps/starter, root README.md, and the docs/planning corpus were never swept, plus three real exported API gaps.

Three genuine API gaps (missed by phase 4), each with a @deprecated alias:

  • parsePattern (was parseRecipe) — packages/core/src/recipes/schema.ts
  • destroyPattern (was destroyRecipe) — packages/dom/src/apply-recipe.ts
  • FIRST_RELEASE_PATTERNS (was FIRST_RELEASE_RECIPES) — packages/core/src/recipes/catalog.ts

apps/starter (a real, user-facing template) fully migrated: main.ts (patternById, compilePattern, applyPattern, bindData({pattern})), index.html prose + headings, README.md (code examples + prose + fixed a genuinely broken /docs/gallery 404 → /docs/patterns). Verified at runtime via a local dev server — inspect() readouts live and incrementing, the shuffle interaction genuinely re-runs bindData/compilePattern/applyPattern against the workspace-linked packages.

Root README.md (the most-visible doc in the repo): the lane table + the old FieldRecipe/Field Formation two-lane split rewritten to the single Field Pattern lane, every code example updated to canonical names, the naming-canon spine fixed.

check:readme literally regexed for "N recipes" in the README — a gate-script drift the rename itself introduced. Fixed to read FIELD_PATTERNS and look for "N patterns".

docs/planning (the critical-path substrate-architecture corpus + field-bridge.md + field-os-frontier.md + docs/research/README.md) swept to Pattern — including a real naming-collision catch: doc 03's proposed FieldFormationReading/formations field (tracking which authored Patterns are applied) is a different, unshipped concept from the already-shipped types.ts formations/activeFormations/FormationChange (the setFormation mode system). Renamed the former to Pattern language, reverted an over-eager rename in doc 02 (activeFormations, which is the real shipped field) back to Formation, and added a clarifying note. Doc 01 (the original 3-lane proposal) is marked SUPERSEDED and kept as historical record. docs/analysis/docs-alignment-report.md (a dated completed report) is correctly left untouched.

Verified: typecheck + build + full test suite (0 fail across all 8 packages/apps) + check:api + check:docs + check:recipes + check:readme + check:links, all green.

A second, deeper pass beyond the phases-0-4 rename: apps/starter, README.md, and the
docs/planning corpus were never swept, plus three real exported API gaps.

Three genuine API gaps (missed by phase 4), each with a @deprecated alias:
- parsePattern (was parseRecipe) - packages/core/src/recipes/schema.ts
- destroyPattern (was destroyRecipe) - packages/dom/src/apply-recipe.ts
- FIRST_RELEASE_PATTERNS (was FIRST_RELEASE_RECIPES) - packages/core/src/recipes/catalog.ts

apps/starter (real, user-facing template) fully migrated: main.ts (patternById,
compilePattern, applyPattern, bindData({pattern})), index.html prose + headings, and
README.md (code examples + prose + the /docs/patterns URL, was a stale /docs/gallery
404). Verified at RUNTIME via a local dev server: inspect() readouts live and
incrementing, the reduce/shuffle interactions genuinely re-run compilePattern() /
applyPattern() / bindData() against the workspace-linked packages.

README.md (root, the most-visible doc in the repo): the lane table, the FieldRecipe/
Field Formation two-lane split rewritten to the single Field Pattern lane, every code
example updated to canonical names, the naming-canon spine fixed, and a genuinely
broken link (/docs/gallery, no such route/redirect exists) fixed to /docs/patterns.

check:readme's catalog-count check literally regexed for "N recipes" in the README --
a gate-script drift the rename itself introduced. Fixed to read FIELD_PATTERNS and
look for "N patterns".

docs/planning (the critical-path substrate-architecture corpus + field-bridge.md +
field-os-frontier.md + docs/research/README.md): swept to Pattern, INCLUDING a real
naming-collision catch -- doc 03's proposed FieldFormationReading/formations field
(tracking which authored Patterns are applied) is a DIFFERENT, unshipped concept from
the already-shipped types.ts formations/activeFormations/FormationChange (the
setFormation MODE system). Renamed the former to Pattern language, reverted an
over-eager rename of the latter (doc 02's activeFormations, which IS the real shipped
field) back to Formation, and added a clarifying note so a future implementer doesn't
collide the two. doc 01 (the original 3-lane "Pattern vs Field Formation vs FieldRecipe"
proposal) is marked SUPERSEDED and kept as historical record, not rewritten.
docs/analysis/docs-alignment-report.md (a dated completed report) is correctly left
untouched, matching the established don't-rewrite-history precedent.

Verified: typecheck + build + full test suite (0 fail across all 8 packages/apps) +
check:api + check:docs + check:recipes + check:readme + check:links, all green.
@vercel

vercel Bot commented Jul 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
fundamental-engine Ready Ready Preview Jul 13, 2026 12:47am

Request Review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3331a09fce

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread README.md
```

Browse and run all 64 recipes at the [recipe gallery](https://fundamental-engine.com/docs/gallery), pick apart a
Browse and run all 64 patterns at the [pattern gallery](https://fundamental-engine.com/docs/patterns), pick apart a

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Send pattern gallery links to /patterns

When readers click this “Browse and run all 64 patterns” link, they land on /docs/patterns, which I checked is the Pattern model/schema page (apps/site/src/pages/docs/patterns.astro) and itself points users to /patterns for the gallery; the actual live catalog route is apps/site/src/pages/patterns/index.astro, with per-pattern pages under /patterns/${id}. This also makes the new starter link to /docs/patterns#priority-well miss the specific pattern, since that anchor is not on the model page. Use /patterns for the gallery and /patterns/priority-well for the specific pattern.

Useful? React with 👍 / 👎.

@zachshallbetter
zachshallbetter merged commit 2ee2709 into main Jul 13, 2026
16 checks passed
@zachshallbetter
zachshallbetter deleted the docs/pattern-rename-remaining-gaps branch July 13, 2026 00:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant