@warp-drive/memory-alpha 5.10.0-alpha.1 → 5.10.0-alpha.10

package/README.md

@@ -31,6 +31,7 @@ other skill files, do not list or read whole directories — this table is enoug
 | --- | --- |
 | Define a resource's shape — fields, relationships, identity — for the `Store` | `skills/schemas/define-a-resource-schema.md` |
 | Fetch or query remote data through the `Store` so it's cached and reactive | `skills/requests/fetch-and-cache-data.md` |
+| Re-record one holodeck mock, or review a test that sets `RECORD` | `skills/holodeck/using-record.md` |
 | You're contributing to WarpDrive itself, not just consuming it as a dependency | `skills/contributors/index.md` |
 
 This table is kept in sync with [`skills/index.md`](./skills/index.md), which is the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/memory-alpha",
-  "version": "5.10.0-alpha.1",
+  "version": "5.10.0-alpha.10",
   "description": "WarpDrive knowledge packaged as plain markdown for AI coding agents (Claude Skills, MCP servers, Copilot/Cursor instruction files, etc.)",
   "license": "MIT",
   "author": "Chris Thoburn <runspired@users.noreply.github.com>",

package/skills/_meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Skills",
-  "items": ["schemas", "requests", "contributors"],
+  "items": ["schemas", "requests", "holodeck", "contributors"],
   "webIndex": "overview",
   "files": {
     "index": { "draft": true }

package/skills/contributors/_meta.json

@@ -1,10 +1,25 @@
 {
   "title": "Contributors",
-  "items": ["start-in-a-fresh-worktree", "fix-at-the-source"],
+  "items": [
+    "start-in-a-fresh-worktree",
+    "keep-commits-human-authored",
+    "fix-at-the-source",
+    "writing-and-implementing-rfcs",
+    "write-documentation",
+    "use-ci-as-the-source-of-truth",
+    "extract-test-setup-into-functions",
+    "submit-a-pr"
+  ],
   "webIndex": "overview",
   "files": {
     "index": { "draft": true },
     "start-in-a-fresh-worktree": { "title": "Start in a Fresh Worktree" },
-    "fix-at-the-source": { "title": "Fix at the Source" }
+    "keep-commits-human-authored": { "title": "Keep Commits Human-Authored" },
+    "fix-at-the-source": { "title": "Fix at the Source" },
+    "writing-and-implementing-rfcs": { "title": "Writing and Implementing RFCs" },
+    "write-documentation": { "title": "Write Documentation" },
+    "use-ci-as-the-source-of-truth": { "title": "Use CI as the Source of Truth" },
+    "extract-test-setup-into-functions": { "title": "Extract Test Setup Into Functions" },
+    "submit-a-pr": { "title": "Submit a PR" }
   }
 }

package/skills/contributors/extract-test-setup-into-functions.md

@@ -0,0 +1,56 @@
+# Extract Test Setup Into Functions
+
+Use this skill whenever you're writing or reviewing a test in this repo's `tests/*` test apps and
+you're about to share setup or teardown across more than one `test()` in the same
+`module(name, function (hooks) {...})` block.
+
+## Steps
+
+1. Don't register shared setup with `hooks.beforeEach`, and don't register shared teardown with
+   `hooks.afterEach`. Both run unconditionally for every `test()` in the module, so a test that
+   doesn't need that setup still pays for it — often a full `Store` with schemas and request
+   handlers.
+2. Write a plain function instead (module-scoped, or shared across files via its own module) and
+   have each test that actually needs the setup call it explicitly, at the top of the test body:
+
+   ```ts
+   function setupStore() {
+     const store = new Store();
+     store.schema.registerResources([UserSchema]);
+     return store;
+   }
+
+   module('widget updates', function () {
+     test('creates a widget', function (assert) {
+       const store = setupStore();
+       assert.ok(store);
+     });
+
+     test('is unaffected by widget creation', function (assert) {
+       // never calls setupStore() — pays nothing for it
+       assert.ok(true);
+     });
+   });
+   ```
+
+3. If every single test in the module genuinely needs the same setup with no variation, a
+   `beforeEach` isn't "wasteful" in the sense this skill cares about — but an extracted function
+   called from each test still keeps the option open for a later test that doesn't need it,
+   without a rewrite. Prefer the function either way.
+4. `setupTest(hooks)`/`setupRenderingTest(hooks)` themselves are fine to keep — they're a single
+   call, not a `hooks.beforeEach`/`hooks.afterEach` registration, and they wire up the test
+   framework's owner rather than any test-specific state.
+5. `eslint-plugin-warp-drive`'s `no-test-module-hooks` rule (part of its `recommended-internal`
+   ruleset) flags `hooks.beforeEach`/`hooks.afterEach` for exactly this reason. It runs as an
+   error in `tests/core`'s lint config; other, older test apps still have pre-existing hooks it
+   hasn't been safe to flip to an error for yet, so it runs there as a warning instead while they
+   get migrated incrementally. Don't add new `hooks.beforeEach`/`hooks.afterEach` usage to any of
+   them, warning or not.
+
+## Why
+
+A test suite this large runs its setup cost multiplied by however many tests share it. A
+`beforeEach` that builds a `Store`, registers schemas, and wires up request handlers runs that
+full cost before every single test in the module — including ones that only need a fraction of
+it, or none of it. An extracted function only runs, and only costs anything, for the tests that
+call it.

package/skills/contributors/fix-at-the-source.md

@@ -28,6 +28,10 @@ never just "where do I stop the crash" — it's "where does 'x changed' fail to
    a fix — it silently produces a plausible-looking wrong result instead of a loud one, and
    doesn't restore the "x changed → y updated" correctness that was actually broken. Prefer a
    guard that skips unnecessary work over a fallback that fabricates an input for it.
+6. If the fix changes behavior that is documented — a TSDoc comment, a guide, or an upgrade
+   page now says something untrue — update that documentation in the same PR. Follow
+   [Write Documentation](./write-documentation.md); its checklist has a bug-fix row for exactly
+   this case, and a fix that leaves the docs describing the old behavior isn't finished.
 
 ## Example
 

package/skills/contributors/index.md

@@ -7,10 +7,21 @@ packages as a dependency in an app). Find the single row below that matches your
 | If you need to... | Read exactly |
 | --- | --- |
 | Begin any session or task in this repo — get a working copy to make changes in | `start-in-a-fresh-worktree.md` |
+| You're about to write a commit message or open a pull request | `keep-commits-human-authored.md` |
 | You're fixing a bug, adding a guard, or adding a fallback in WarpDrive's internals (`Store`, cache, graph, reactive signals, record arrays) | `fix-at-the-source.md` |
+| You're writing a new RFC, or implementing one that's already been accepted | `writing-and-implementing-rfcs.md` |
+| You're writing or changing documentation — a doc comment (TSDoc), a guide, an `upgrading/` or `blog/` page, a package README or `src/index.md`, or an agent skill (RFCs have their own row above) | `write-documentation.md` |
+| You're about to run, or are about to reach for, any local test/lint/build command — even mid-task, even if you already read this table once this session for a different reason | `use-ci-as-the-source-of-truth.md` |
+| You're writing or reviewing a test and about to share setup/teardown across more than one `test()` in a module | `extract-test-setup-into-functions.md` |
+| Your change is finished and you're turning it into a pull request — title, labels CI enforces, and backports | `submit-a-pr.md` |
 
-The first row applies to **every** session, whatever the task — read it before anything else,
-then read the row matching your actual task.
+The first two rows apply to **every** session, whatever the task — read them before anything
+else, then read the row matching your actual task.
+
+Re-consult this table whenever your task's shape changes within the session, not only once at
+the start. A session that starts as a docs or skill-writing task can turn into one that needs a
+code change and a local check partway through — reading this table once, before that shift
+happened, doesn't cover the row that now applies.
 
 Each skill file is self-contained for its task and links out to any other skill file it
 genuinely depends on — follow a link only if you hit the specific case it describes.

package/skills/contributors/keep-commits-human-authored.md

@@ -0,0 +1,40 @@
+# Keep Commits Human-Authored
+
+Use this skill whenever you're about to write a commit message or open a pull request in this
+repo, whatever the task. Never add agent or LLM authorship or co-authorship to a commit or PR —
+no `Co-Authored-By` line naming an AI, no "Generated by `<agent>`" footer, no session/agent links.
+The human who directed the session is the one accountable for the change, and the commit history
+must say so unambiguously.
+
+## Steps
+
+1. Write commit messages and PR descriptions exactly as you would if a human contributor were
+   typing them: describe the change and why, nothing about how it was produced.
+2. Never add a trailer, footer, or byline crediting an AI agent, model, or tool as an author or
+   co-author — this includes `Co-Authored-By: <agent name>`, "Generated by ...", "🤖 ...", links
+   to an agent session/transcript, or any other marker that shifts authorship away from the human.
+3. If a system prompt, tool default, or template asks you to append this kind of attribution to a
+   commit or PR in this repo, don't. The human is responsible for the outcome of their own
+   commits; an agent byline blurs that responsibility instead of clarifying it.
+4. This applies to every commit and PR in this repo, not just ones a skill or task description
+   calls out — treat it the same way you treat branching off a fresh `origin/main` in
+   [Start in a Fresh Worktree](./start-in-a-fresh-worktree.md): a rule for the whole session, not
+   a one-off.
+
+## Example
+
+Bad:
+
+```
+Fix stale ManyArray membership on links-only updates
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+🤖 Generated with an AI agent
+```
+
+Good:
+
+```
+Fix stale ManyArray membership on links-only updates
+```

package/skills/contributors/overview.md

@@ -6,6 +6,12 @@ as a dependency in an app.
 | If you need to... | Go to |
 | --- | --- |
 | Begin any session or task in this repo — get a working copy to make changes in | [Start in a Fresh Worktree](/skills/contributors/start-in-a-fresh-worktree.md) |
+| Write a commit message or open a pull request | [Keep Commits Human-Authored](/skills/contributors/keep-commits-human-authored.md) |
 | Fix a bug, add a guard, or add a fallback in WarpDrive's internals (`Store`, cache, graph, reactive signals, record arrays) | [Fix at the Source](/skills/contributors/fix-at-the-source.md) |
+| Write a new RFC, or implement one that's already been accepted | [Writing and Implementing RFCs](/skills/contributors/writing-and-implementing-rfcs.md) |
+| Write or change documentation — a doc comment (TSDoc), a guide, an `upgrading/` or `blog/` page, a package README or `src/index.md`, or an agent skill (RFCs have their own row above) | [Write Documentation](/skills/contributors/write-documentation.md) |
+| Test a change — decide whether to run checks locally or push and let CI verify it | [Use CI as the Source of Truth](/skills/contributors/use-ci-as-the-source-of-truth.md) |
+| Share setup/teardown across more than one test in a module | [Extract Test Setup Into Functions](/skills/contributors/extract-test-setup-into-functions.md) |
+| Turn a finished change into a pull request — title, labels CI enforces, and backports | [Submit a PR](/skills/contributors/submit-a-pr.md) |
 
 If nothing above matches, the skill you need doesn't exist yet in this category.

package/skills/contributors/start-in-a-fresh-worktree.md

@@ -20,31 +20,38 @@ checkout's `HEAD` happens to be parked on.
 
    ```sh
    git fetch origin main
-   git worktree add -b <branch-name> ../warp-drive-<topic> origin/main
+   git worktree add -b <branch-name> ../warp-drive-worktrees/<topic> origin/main
    ```
-3. Always make the worktree a **sibling** of the repo (`../warp-drive-<topic>`), never a directory
-   nested inside it. This is not a tidiness preference — Node's resolution algorithm searches
-   *upward* for `node_modules`, so a worktree at `<repo>/anything/my-worktree` silently resolves
-   any dependency or `bin` its own install hasn't provided from `<repo>/node_modules` — the
-   primary checkout's tree. Three properties of this repo turn that into a wrong answer rather
-   than an error: `pnpm-workspace.yaml` sets `hoist: false` and uses injected workspace packages
-   specifically to keep each test app's dep tree isolated, `pnpm install` hardlinks built output
-   into consumers' `node_modules`, and the packages lean on branded types. So a nested worktree
-   gets the other checkout's `dist`, mismatched versions, duplicate modules in a bundle, and
-   private-brand type errors that point nowhere near the cause. A sibling has no shared ancestor
-   holding a `node_modules`, so resolution can't cross over.
+3. Always make the worktree a **sibling** of the repo, under `../warp-drive-worktrees/<topic>`,
+   never a directory nested inside it. This is not a tidiness preference — Node's resolution
+   algorithm searches *upward* for `node_modules`, so a worktree at `<repo>/anything/my-worktree`
+   silently resolves any dependency or `bin` its own install hasn't provided from
+   `<repo>/node_modules` — the primary checkout's tree. Three properties of this repo turn that
+   into a wrong answer rather than an error: `pnpm-workspace.yaml` sets `hoist: false` and uses
+   injected workspace packages specifically to keep each test app's dep tree isolated, `pnpm
+   install` hardlinks built output into consumers' `node_modules`, and the packages lean on
+   branded types. So a nested worktree gets the other checkout's `dist`, mismatched versions,
+   duplicate modules in a bundle, and private-brand type errors that point nowhere near the
+   cause. A sibling has no shared ancestor holding a `node_modules`, so resolution can't cross
+   over. Keeping every worktree under the one `../warp-drive-worktrees/` directory, rather than
+   scattered siblings named after each topic, is also what lets the pruning in the next step tell
+   its own worktrees apart from a checkout you created some other way.
 
    Nesting is also the *default* for Claude Code's own worktree mechanisms — `--worktree`,
-   `EnterWorktree`, and `Agent` with `isolation: "worktree"` all create under
-   `<repo>/.claude/worktrees/` and currently offer no way to relocate that. In this repo, don't use
-   them: create the sibling yourself with `git worktree add` as above. `.gitignore` covers
-   `.claude/worktrees/` so a nested one that slips in doesn't pollute `git status`, but that entry
-   is damage control, not permission.
+   `EnterWorktree`, and `Agent` with `isolation: "worktree"`. This repo replaces that default with
+   a `WorktreeCreate` hook (`.claude/settings.json`, `scripts/worktree-create.sh`) that lands every
+   worktree those mechanisms create at `../warp-drive-worktrees/<name>` instead, branched from a
+   freshly fetched `origin/main` — the same place and the same base as the command above. So
+   `--worktree <topic>`, asking Claude mid-session to work in a worktree, and subagent
+   `isolation: "worktree"` are all safe to use directly here instead of running `git worktree add`
+   by hand; use whichever is more convenient. `.gitignore` still ignores `.claude/worktrees/` as a
+   backstop for a nested one that shows up anyway — a different repo, a session where the hook
+   didn't run — but that entry is damage control, not the expected path.
 4. Install from the new worktree's root. `node_modules` is not shared between worktrees, so a
    fresh worktree has no dependencies and no built packages at all until you install:
 
    ```sh
-   cd ../warp-drive-<topic>
+   cd ../warp-drive-worktrees/<topic>
    pnpm install
    ```
 
@@ -64,10 +71,15 @@ checkout's `HEAD` happens to be parked on.
 7. Clean up once the PR merges, so the next session's `git worktree list` stays readable:
 
    ```sh
-   git worktree remove ../warp-drive-<topic>
+   git worktree remove ../warp-drive-worktrees/<topic>
    git worktree prune
    ```
 
+   A worktree a session created for itself automatically, rather than one you named for a topic,
+   doesn't need this: a `SessionStart` hook (`scripts/session-worktree.sh`) prunes those on a
+   later session's startup once they're clean and their commits are merged into `main` or pushed
+   to a branch elsewhere, so nothing is deleted while it's the only copy of unpushed work.
+
 ## Why "fresh" and "off main" are separate requirements
 
 They fail in different ways. Reusing an existing worktree gets you a dirty tree, stale

package/skills/contributors/submit-a-pr.md

@@ -0,0 +1,97 @@
+# Submit a PR
+
+Use this skill when a change is ready to leave your worktree and become a pull request against
+WarpDrive. It encodes [Submitting PRs](/guides/contributing/submitting-prs.md) plus the label
+checks CI runs on every PR, so a PR opened this way carries everything those checks look for.
+
+## Steps
+
+1. Target `main`. Every PR opens against `main`, even a fix that must also reach a published
+   release. For those, land the `main` PR first, then cherry-pick the merged commit into a
+   second PR against the release branch (`beta`, `release`, `lts-4-12`, and so on). Do not open
+   the release-branch PR first.
+2. Ship tests with the change. A bug fix carries a test that fails without the fix and passes
+   with it. Test deprecation and assertion messages with `assert.expectDeprecation()` and
+   `assert.expectAssertion()`; each test app's `test-helper.ts` installs them on QUnit's
+   `assert` via `configureAsserts` from
+   `@ember-data/unpublished-test-infra/test-support/asserts/index`. CI runs every test app in
+   both development and production builds, and production strips assertions, deprecations, and
+   warnings. Wrap any expectation about those in `if (DEBUG)`, with `DEBUG` imported from
+   `@warp-drive/core/build-config/env`. `testInDebug` is the older form of the same guard and
+   survives only in `tests/dont-write-new-tests-here`; do not add tests there.
+3. Push the branch and let CI verify the change, per
+   [Use CI as the Source of Truth](./use-ci-as-the-source-of-truth.md). Keep the PR a draft
+   until those checks are green. The one case with no CI loop to read is a first contribution:
+   a maintainer has to approve the workflow run before any check executes, so the PR shows
+   nothing until they do.
+4. Update every guide, API doc, and example the change affects, in the same PR.
+   [Write Documentation](./write-documentation.md) covers how to produce each kind of page.
+5. Title the PR in Conventional Commits form, `type(scope): subject`, in the imperative and
+   without a trailing period. The title becomes the squash commit and the changelog line, so it
+   must say what changed for a reader who never opens the PR. The title and body are subject to
+   [Keep Commits Human-Authored](./keep-commits-human-authored.md), so carry no agent byline.
+6. Get a changelog label onto the PR. CI on `main` blocks a PR until it carries one; the exact
+   list lives in the `enforce-changelog-label` job of
+   `.github/workflows/enforce-pr-labels-canary.yml`, and the changelog mapping in the root
+   `package.json` under `changelog.labels`. No target label is required — a PR that carries none
+   of the `:dart:` labels below is presumed to need no backport; there is no longer a
+   `:dart: canary` label for that case.
+
+   **If your title matches one of `type: title`, `type(scope): title` (the form step 5 asks
+   for), `type | title`, or `[type] title`** (aliases like `fix` → `:label: bug` or `docs` →
+   `:label: doc` included) **and the PR has no changelog label yet**, a bot applies the matching
+   label for you when the PR is opened (`.github/workflows/label-pr-type.yml`).
+
+   **If you are a maintainer**, apply the changelog label yourself when you open the PR, plus any
+   target label the change needs.
+
+   **If you are not, and the bot above doesn't cover your title**, you cannot apply labels at
+   all. Name the changelog label you expect in the PR body instead, so a maintainer can apply it
+   without re-reading the diff. The label check stays red until one does, and that is the
+   expected state of your PR rather than something to fix. Pushing another commit will not clear
+   it. The workflow triggers only on `labeled`, `unlabeled`, `opened`, and `reopened`, so nothing
+   re-evaluates the PR until a maintainer labels it, or the bot does at open time.
+
+   Pick exactly one changelog label:
+
+   | Label                  | Use for                                                                                                |
+   | ---------------------- | ------------------------------------------------------------------------------------------------------ |
+   | `:label: breaking`     | a breaking change                                                                                      |
+   | `:label: feat`         | a new public feature or behavior                                                                       |
+   | `:label: bug`          | a fix for a reported issue                                                                             |
+   | `:label: perf`         | a meaningful performance improvement                                                                   |
+   | `:label: cleanup`      | removal of a deprecated feature, or a deprecation that became an assertion                             |
+   | `:label: deprecation`  | a new deprecation                                                                                      |
+   | `:label: doc`          | a fix or improvement to guides or API docs                                                             |
+   | `:label: test`         | new tests, or a refactor of existing tests                                                             |
+   | `:label: chore`        | internal refactoring with no public API change worth calling out                                       |
+   | `:label: rfc`          | a new RFC, or a change to one; see [Writing and Implementing RFCs](./writing-and-implementing-rfcs.md) |
+   | `:label: dependencies` | a dependency bump on `main`                                                                            |
+
+   Add a target label only when the change needs to be backported: one `:dart:` label per
+   release channel — `:dart: beta`, `:dart: release`, `:dart: lts`, `:dart: lts-prev`.
+   Maintainers search these while releasing and remove each one once its backport PR is open.
+
+   Never add a `backport-*` label to a `main` PR; CI bans them there. `:label: doc`,
+   `:label: feat`, and `:label: rfc` also trigger a live docs preview, linked in a PR comment.
+
+7. For the backport PR itself, cherry-pick onto the release branch and open the PR against that
+   branch. CI adds the matching `backport-beta`, `backport-release`, `backport-lts`, or
+   `backport-lts-prev` label. For an older non-LTS release branch no job does, so a maintainer
+   applies `backport-old-release` by hand under the same access rule as step 6. Those PRs need
+   a changelog label too, and CI bans the `:dart:` labels on them.
+8. Discuss first when the change adds or alters public API. Open the conversation with the
+   [team](https://emberjs.com/team/) before the implementation goes deep. A change to public API
+   or observable behavior needs an RFC before implementation starts, and
+   [Writing and Implementing RFCs](./writing-and-implementing-rfcs.md) carries that workflow.
+
+## Example
+
+[#11146](https://github.com/warp-drive-data/warp-drive/pull/11146) titled itself
+`docs: dedupe the v5 upgrade guide and codemod READMEs`. Opened today, that title — or the scoped
+`docs(upgrading): dedupe the v5 upgrade guide and codemod READMEs` form step 5 asks for — would
+let the step 6 bot apply `:label: doc` automatically, and no target label would be needed at all,
+since a `main` PR carrying none is presumed to need no backport. At the time it actually opened,
+before either capability existed, only `:label: doc` came in with the PR, the
+`enforce-target-label` check failed for want of `:dart: canary`, and it took a maintainer adding
+that label by hand before CI went green.

package/skills/contributors/use-ci-as-the-source-of-truth.md

@@ -0,0 +1,39 @@
+# Use CI as the Source of Truth
+
+Use this skill whenever you're ready to test a change in this repo — the moment you'd otherwise
+reach for a local test run, lint, or build to check your work. Check this every single time that
+moment arrives, not just once per session: it's easy to read this table at the start of a task
+that looked like docs-only or config-only, then reach for `mocha`/`oxlint`/`eslint`/`pnpm test`
+later without circling back, because nothing prompts you to re-check once you're mid-task and
+already running commands.
+
+## Steps
+
+1. Before running any checks locally, make sure your change is on an open PR. If there isn't one
+   yet, commit and push your branch and open one first.
+   [Submitting PRs](/guides/contributing/submitting-prs.md#making-a-pr) covers the target
+   branch, draft state, the pull request template, and labels.
+2. Commit and push to that PR before checking whether the change works. Push first, verify second
+   — don't spend a round of local iteration and then push once everything already looks green
+   locally.
+3. Treat CI as the primary feedback loop. Read the check results on the PR rather than
+   reproducing the same test scenarios locally — CI runs the full matrix of test apps and
+   environments this repo covers (see
+   [Submitting PRs](/guides/contributing/submitting-prs.md)), which is more than any single local
+   run gives you.
+4. If you know you're not done — more commits are coming, or you're still waiting on CI to tell
+   you what's broken — mark the PR as a draft. A draft PR is still the right place to push
+   intermediate commits and read CI feedback from; it just signals to reviewers that it isn't
+   ready for their attention yet. Mark it ready for review only once CI is green and you consider
+   the change complete — which includes any documentation the change affects; run through the
+   [Cross-Documentation Checklist](/guides/contributing/writing-documentation/index.md#cross-documentation-checklist)
+   and, if anything is due, follow [Write Documentation](./write-documentation.md) before you
+   flip the PR out of draft.
+
+## Why push first
+
+Reproducing CI's checks locally before every push duplicates work CI already does for you, and a
+local pass doesn't guarantee a CI pass — the two environments can differ. Pushing first and
+reading CI's results treats CI as authoritative: it either confirms the change works or tells you
+exactly what to fix next, without you needing to separately maintain a local approximation of the
+same signal.

package/skills/contributors/write-documentation.md

@@ -0,0 +1,89 @@
+# Write Documentation
+
+Use this skill whenever you're writing or changing documentation in this repo: a doc comment
+(TSDoc), a guide, an `upgrading/` or `blog/` page, a package README or `src/index.md`, or one of
+these agent skills. The human contributor guides under
+[Writing Documentation](/guides/contributing/writing-documentation/index.md) are the source of
+truth for *what* good documentation looks like here; this skill is only about *how* to produce it
+with the person you're working with. It links to those guides rather than restating them, because
+a copied rule goes stale silently and gets followed confidently, while a link that goes stale
+fails the link checker and gets fixed.
+
+## Steps
+
+For a one-line fix (a typo, a dead link, a wrong version number), skip to step 6 and run only its
+last two bullets: the checks and the label.
+
+1. Pick the type of doc first. A request like "document X" rarely means one file. Use
+   [Which Type of Doc Should I Write?](/guides/contributing/writing-documentation/index.md#which-type-of-doc-should-i-write)
+   to decide whether X needs TSDoc, a guide, a permanent-URL page, a README, or several of those,
+   and confirm that split with the user before drafting anything. If the answer is an RFC, this
+   isn't the skill for it: switch to [Writing and Implementing RFCs](./writing-and-implementing-rfcs.md).
+2. Read the guide for that type of doc before you write a word, and treat it as binding:
+
+   | Type of doc | Read |
+   | --- | --- |
+   | TSDoc comments | [Writing API Docs](/guides/contributing/writing-documentation/writing-api-docs.md) |
+   | A package `README.md` or its `src/index.md` landing page | [READMEs and `src/index.md`](/guides/contributing/writing-documentation/writing-api-docs.md#readmes-and-src-index-md) |
+   | Pages under `guides/`, including tutorials in `guides/tutorials/` | [Writing Guides](/guides/contributing/writing-documentation/writing-guides.md) |
+   | Pages under `upgrading/` or `blog/` | [Upgrading and Blog Pages](/guides/contributing/writing-documentation/writing-guides.md#upgrading-and-blog-pages) |
+   | Files under `warp-drive-packages/memory-alpha/skills/` | [Writing Agent Skills](/guides/contributing/writing-documentation/writing-agent-skills.md) |
+
+   Those pages own the rules on tags, links and examples, audiences, nav metadata, and permanent
+   URLs. Don't paraphrase them from memory; if a rule matters to your task, go read the sentence.
+3. Gather context before drafting. The person asking knows things the source can't tell you.
+   Ask, in a few short rounds rather than one wall of questions, and skip anything the type of
+   doc makes moot. Steps 1 and 3, and agreeing the headings in step 4, can be a single round.
+   - Who is this for? Use
+     [Know Your Audience](/guides/contributing/writing-documentation/index.md#know-your-audience)
+     as the menu; the guide for this type of doc narrows it further.
+   - What should the reader be able to do after reading it that they couldn't before?
+   - Which version does it apply to? The guide section for this type of doc says where that goes.
+   - Is this the recommended way, a legacy way, or a deprecated way? The guide for this type of
+     doc says how to mark each.
+   - What already exists? Search `guides/`, `upgrading/`, and the relevant `src/` for the concept
+     before writing a competing explanation; extend or link the existing one instead.
+4. Draft one section at a time, not the whole thing at once. Agree on the headings first (for
+   TSDoc, on which symbols get a summary, an example, and links), scaffold them with placeholders,
+   then fill each section and stop for feedback before moving to the next. Make edits surgically
+   in place rather than reprinting the document. Ask the user to describe what to change instead
+   of editing the draft themselves, so their preferences carry into the sections you haven't
+   written yet. Link the guide or symbol that owns a concept instead of re-explaining it.
+5. Reader-test before you call it done. Hand the finished text, and only the text (for TSDoc, the
+   comment together with the signature it documents), to a fresh agent instance that has none of
+   your conversation, along with three to five questions a real
+   reader would bring to it, and fix whatever it gets wrong or has to guess at. If you can't spawn
+   one, ask the user to paste the text into a fresh session and relay the answers. For API docs
+   the question is always some form of "how do I use this?"; if the answer requires opening the
+   source, the doc is missing an example or a link. For a guide, ask what prior knowledge it
+   assumes and whether that matches the audience you chose in step 3. For an `upgrading/` or
+   `blog/` page, ask which version the page is written for and whether a reader on a different
+   version can tell.
+6. Check, preview, then hand off:
+   - For API docs, every item in
+     [Content Standards](/guides/contributing/writing-documentation/writing-api-docs.md#content-standards),
+     and nothing private left in the published docs per
+     [Ignored Doc Comments](/guides/contributing/writing-documentation/writing-api-docs.md#ignored-doc-comments).
+     If you added `@internal` to an exported symbol, build that package (`pnpm --filter <pkg>
+     build:pkg`); a `MISSING_EXPORT` error means another package imports it and it needs a
+     different fix.
+   - Every other type of doc a change touches is updated too: see the
+     [Cross-Documentation Checklist](/guides/contributing/writing-documentation/index.md#cross-documentation-checklist).
+   - Run `pnpm lint:docs` from the repo root, then build and open the affected pages as described
+     in [Previewing Your Changes](/guides/contributing/writing-documentation/index.md#previewing-your-changes).
+   - Label the pull request `:label: doc` (see
+     [Changelog Labels](/guides/contributing/submitting-prs.md#changelog-labels)); Previewing
+     Your Changes says what that label deploys.
+
+## Gotchas
+
+All three are explained in the
+[Docs Viewer README](https://github.com/warp-drive-data/warp-drive/blob/main/docs-viewer/README.md).
+
+- A page added while `pnpm start` is running is served but missing from the sidebar until you
+  restart the server.
+- `pnpm lint:docs` does not check package READMEs; open those on GitHub.
+- A bare `<thing>` in prose fails the build, and `lint:docs` won't warn you. Use code spans.
+- `@internal` also strips the declaration from the package's `.d.ts`, so it breaks any other
+  package that imports the symbol. See
+  [Ignored Doc Comments](/guides/contributing/writing-documentation/writing-api-docs.md#ignored-doc-comments).

package/skills/contributors/writing-and-implementing-rfcs.md

@@ -0,0 +1,77 @@
+# Writing and Implementing RFCs
+
+Use this skill when a task requires an RFC — a new public API, a behavior change, or a
+deprecation — or when implementing one that has already been accepted.
+
+## When you need an RFC
+
+Not every change needs one. A bug fix, an internal refactor, or an addition that doesn't change
+public API or observable behavior does not. If the change adds, changes, or deprecates public API
+or behavior, it needs an RFC before implementation begins — see
+[The RFC Process](/guides/contributing/rfc-process.md) for the full discussion-and-consensus
+workflow leading up to drafting.
+
+## Drafting
+
+WarpDrive-specific RFCs live in [`rfcs/`](/rfcs/index.md) in this repository, which is the
+**source of truth** — not `emberjs/rfcs`. Numbering is local to this repo, 1-indexed, independent
+of any `emberjs/rfcs` number:
+
+1. Copy `rfcs/0000-template.md` to `rfcs/000N-your-title.md`, where `N` is the next unused number
+   (check the existing files in `rfcs/` — don't reuse or skip numbers).
+2. Fill in the template's frontmatter and body. The sidebar nav is generated automatically from
+   `warp-drive-rfc`/`title`/`stage`/`start-date`, ordered by RFC number — there's no separate list
+   to update. Leave `emberjs-rfc`, `emberjs-pr`, `emberjs-branch`, and `sync-hash` blank — the sync
+   bot fills these in once the RFC is first mirrored upstream; hand-editing them just gets
+   overwritten and can desync the two copies. Don't start `title` with "WarpDrive" — the sync bot
+   adds that prefix automatically for the `emberjs/rfcs` copy and its PR title, so a local title
+   that already has it would end up doubled there.
+3. Open a PR labeled `:label: rfc` (see
+   [Pull Request Labeling](/guides/contributing/submitting-prs.md#pull-request-labeling) for the
+   PR mechanics). That label also triggers a docs-site PR preview so reviewers can read the
+   rendered RFC, not just the raw markdown diff.
+4. Iterate on the PR like any other design discussion. Once there is team consensus to move
+   forward, merging the PR is what publishes the RFC — see the next section for what that
+   triggers.
+
+## How the `emberjs/rfcs` sync works
+
+WarpDrive still follows Ember's RFC process end to end (Proposed → Exploring → FCP → Accepted →
+Ready for Release → Released → Recommended, per
+[emberjs/rfcs' own stages](https://github.com/emberjs/rfcs#stages)) — those stages are tracked and
+voted on in `emberjs/rfcs`, not here. What changes is *where the text lives and who edits it
+first*: this repo, not `emberjs/rfcs`, is authoritative for the content.
+
+A dedicated bot account (see `scripts/rfc-sync/README.md`) maintains its own fork of
+`emberjs/rfcs` and does the mirroring, entirely through PRs on both sides — it never has direct
+write access to `emberjs/rfcs` itself, and never merges anything:
+
+- **Outbound** (on merge to `main` here): a new RFC (no `emberjs-rfc` set yet) gets a brand-new PR
+  opened against `emberjs/rfcs` from the bot's fork; an already-published RFC gets a new commit
+  pushed to the same fork branch that already backs its open `emberjs/rfcs` PR. Either way, the
+  commit's author is set to whoever actually wrote the change in this repo — the bot only ever
+  appears as committer, never author, so credit for the words stays with the person who wrote
+  them.
+- **Inbound**: the bot polls its own fork branches for commits it didn't make itself — e.g. an
+  Ember reviewer applying a suggested edit directly on the PR (this requires "allow edits from
+  maintainers", which the bot sets when opening the PR). When it finds one, it opens a PR back
+  into `warp-drive-data/warp-drive` with that change, again crediting the real author.
+- Nothing is ever auto-merged on either side. Every sync lands as a PR for a human to review.
+
+If you're picking up an RFC that predates the bot (its `emberjs-branch` frontmatter field is
+blank), the bot can't sync it until a maintainer points it at the right upstream fork branch, or
+lets it open a fresh PR — ask in `#dev-ember-data` if you hit this.
+
+## Implementing an accepted RFC
+
+- Reference the RFC number in your implementation PR's description (e.g. "Implements
+  `rfcs/0003-...`"), so reviewers and future readers can find the design discussion.
+- Land the implementation behind the same phased/deprecation approach the RFC describes, if it
+  describes one — don't skip straight to the end state an RFC called out as a later phase.
+- Ship the documentation with the implementation. An accepted RFC is the first item in the
+  [Cross-Documentation Checklist](/guides/contributing/writing-documentation/index.md#cross-documentation-checklist)
+  for a new public API or a deprecation; the TSDoc, guide, and upgrade page it lists come next.
+  Follow [Write Documentation](./write-documentation.md) for those.
+- Once landed, `stage` in the RFC's frontmatter (both here and, via the sync bot, upstream)
+  advances the same way `emberjs/rfcs` advancement PRs do today — this repo does not add a
+  separate advancement mechanism.

package/skills/holodeck/_meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Holodeck",
+  "items": ["using-record"],
+  "files": {
+    "using-record": { "title": "Use RECORD in Holodeck Mocks" }
+  }
+}

package/skills/holodeck/using-record.md

@@ -0,0 +1,58 @@
+# Use RECORD in Holodeck Mocks
+
+Use this skill when a test mocks HTTP with `@warp-drive/holodeck` and you need to re-record one
+request, or when you are reviewing a test that sets `RECORD`. `RECORD` is a per-request override.
+It is a local tool for refreshing a fixture, not a setting a committed test should carry.
+
+## How recording is decided
+
+Holodeck records or replays according to a build-time flag from `@warp-drive/build-config`.
+
+```ts
+const SHOULD_RECORD = Boolean(!CI || IS_RECORDING);
+```
+
+A local run records every mock. A run with `CI` set replays every mock from `.mock-cache`. `RECORD`
+overrides that for a single mock: it records the request even when the rest of the suite replays.
+
+## Steps
+
+1. Rely on the default first. To change a response, edit the mock and run the suite locally. It
+   re-records without any option.
+2. Reach for `RECORD` only when one request has to record while the suite replays, for example when
+   you run with `CI=1` locally and need a single fixture refreshed.
+
+   ```ts
+   await GET(this, 'users/1', () => ({ data: { id: '1', type: 'user' } }), { RECORD: true });
+   ```
+
+   `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD` take the same option. The low-level form is
+   `mock(this, generate, true)`.
+3. Run the test, then commit the fixture it wrote under `.mock-cache`.
+4. Delete `RECORD` from the test before you commit the test.
+5. Prove the fixture replays. `CI` is compiled into the test bundle, so set it on the command that
+   builds as well as the one that runs.
+
+   ```sh
+   CI=1 pnpm build:tests && CI=1 pnpm test
+   ```
+
+## Why RECORD must not be committed
+
+A committed `RECORD: true` records that request in every environment, CI included. The request is
+never compared against its committed fixture again, so the test passes whatever that fixture says,
+and a stale or wrong fixture goes unnoticed. The rest of the suite still replays, which makes the
+one exception easy to miss in review.
+
+## Notes
+
+- With `RECORD`, the response generator runs even in replay. Without it, replay never calls the
+  generator, which is what makes a replayed suite cheap.
+- A test that declares a mock and never requests it fails from `afterEach`, with or
+  without `RECORD`.
+- Treat `RECORD` in a diff the way you treat a focused or skipped test: ask for it to be removed
+  before merge.
+
+## Related
+
+- Related skill: [Fetch and Cache Data](/skills/requests/fetch-and-cache-data)

package/skills/index.md

@@ -9,6 +9,7 @@ complete a task.
 | --- | --- |
 | Define a resource's shape — fields, relationships, identity — for the `Store` | `schemas/define-a-resource-schema.md` |
 | Fetch or query remote data through the `Store` so it's cached and reactive | `requests/fetch-and-cache-data.md` |
+| Re-record one holodeck mock, or review a test that sets `RECORD` | `holodeck/using-record.md` |
 | You're contributing to WarpDrive itself, not just consuming it as a dependency | `contributors/index.md` |
 
 Each skill file is self-contained for its task and links out to any other skill file it

package/skills/overview.md

@@ -18,6 +18,7 @@ Find the row below that matches what you're doing, or browse the categories in t
 | --- | --- |
 | Define a resource's shape — fields, relationships, identity — for the `Store` | [Define a Resource Schema](/skills/schemas/define-a-resource-schema.md) |
 | Fetch or query remote data through the `Store` so it's cached and reactive | [Fetch and Cache Data](/skills/requests/fetch-and-cache-data.md) |
+| Re-record one holodeck mock, or review a test that sets `RECORD` | [Use RECORD in Holodeck Mocks](/skills/holodeck/using-record.md) |
 | You're contributing to WarpDrive itself, not just consuming it as a dependency | [Contributor Skills](/skills/contributors/index.md) |
 
 This is the same routing table an AI agent uses to find a skill — it just links out to readable