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

package/README.md

@@ -8,13 +8,11 @@
     />
 </p>
 
-![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
-![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![NPM Stable Version](https://img.shields.io/npm/v/%40warp-drive%2Fmemory-alpha/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/%40warp-drive%2Fmemory-alpha.svg?style=flat&color=fdb155)
 ![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
-[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
-)
-[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
-)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS)
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S)
 
 # @warp-drive/memory-alpha
 
@@ -32,6 +30,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` |
+| Look up a guide, upgrade note, or API reference page that no row above covers — a concept, an option, a signature | `skills/docs/read-the-docs-as-markdown.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
@@ -113,3 +112,63 @@ const skill = readFileSync(pkgPath.replace('package.json', 'skills/schemas/defin
 
 Or point an MCP filesystem/docs server, a Claude Code skill, or any other agent tooling at the
 installed package's `skills` directory.
+
+### ♥️ Credits
+
+ <details>
+   <summary>Brought to you with ♥️ love by <a href="https://emberjs.com" title="EmberJS">🐹 Ember</a></summary>
+
+  <style type="text/css">
+    img.project-logo {
+       padding: 0 5em 1em 5em;
+       width: 100px;
+       border-bottom: 2px solid #bbb;
+       margin: 0 auto;
+       display: block;
+     }
+    details > summary {
+      font-size: 1.1rem;
+      line-height: 1rem;
+      margin-bottom: 1rem;
+    }
+    details {
+      font-size: 1rem;
+    }
+    details > summary strong {
+      display: inline-block;
+      padding: .2rem 0;
+      color: #000;
+      border-bottom: 3px solid #bbb;
+    }
+
+    details > details {
+      margin-left: 2rem;
+    }
+    details > details > summary {
+      font-size: 1rem;
+      line-height: 1rem;
+      margin-bottom: 1rem;
+    }
+    details > details > summary strong {
+      display: inline-block;
+      padding: .2rem 0;
+      color: #555;
+      border-bottom: 2px solid #555;
+    }
+    details > details {
+      font-size: .85rem;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      details > summary strong {
+        color: #fff;
+      }
+    }
+    @media (prefers-color-scheme: dark) {
+      details > details > summary strong {
+        color: #afaba0;
+      border-bottom: 2px solid #afaba0;
+      }
+    }
+  </style>
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/memory-alpha",
-  "version": "5.10.0-alpha.10",
+  "version": "5.10.0-alpha.12",
   "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", "holodeck", "contributors"],
+  "items": ["schemas", "requests", "holodeck", "docs", "contributors"],
   "webIndex": "overview",
   "files": {
     "index": { "draft": true }

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

@@ -64,10 +64,17 @@ checks CI runs on every PR, so a PR opened this way carries everything those che
    | `: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: chore`        | internal refactoring, or a fix scoped only to build tooling, lint/CI config, or other dev-experience-only code, with no public API or runtime-behavior 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`                                                                            |
 
+   `:label: bug` is for a fix a consumer of the published packages could actually hit — a runtime
+   behavior change. A PR that only touches build/lint/infra/DX surfaces (a broken `turbo` task, a
+   flaky CI workflow, an eslint rule, a codemod script) is `:label: chore` even though you're
+   "fixing" something, because nothing in the published packages changes. Title that PR
+   `chore(scope): subject`, not `fix(scope): subject` — the bot in step 5 maps a `fix:`-typed
+   title straight to `:label: bug`, which would misfile it.
+
    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.

package/skills/contributors/write-documentation.md

@@ -50,18 +50,36 @@ last two bullets: the checks and the label.
    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.
+   comment together with the signature it documents), to one fresh agent instance per audience
+   the guide for this type of doc names, each with none of your conversation, run in parallel.
+   The guide's first-named audience is the primary one: fix whatever that reader gets wrong or
+   has to guess at, and fix a secondary reader's gap only when the fix is cheap, usually a link,
+   so the page does not drift toward nobody. If you can't spawn agents, ask the user to paste each
+   whole prompt, text included, into a fresh session and relay the answers. Each prompt has three
+   parts, and the first is the one that is easy to skip:
+   - Tell the agent who it is. Name its audience using one of the bold labels in
+     [Know Your Audience](/guides/contributing/writing-documentation/index.md#know-your-audience),
+     and say what that reader already knows and does not: an existing user reading API docs knows
+     the project's vocabulary but not the concept behind the thing this page documents; a hobbyist
+     reading a tutorial knows their own stack and nothing about ***Warp*Drive**. Without this the
+     agent judges every unexplained term as a gap, or none of them, and either answer is noise.
+   - Give it three to five questions that reader would bring to the text. For API docs, a
+     package's `src/index.md` landing page included, 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 README, ask whether the reader would install the package and what they would type
+     first. For a guide, ask what prior knowledge it assumes and whether that matches the audience
+     you named. For an `upgrading/` or `blog/` page, ask which version the page is written for and
+     whether a reader on a different version can tell.
+   - Ask it to say, for each answer, whether it came from the text, needed a guess, or could not
+     be answered, and to list the terms it did not know. Judge that list against the audience you
+     named, not against zero knowledge; a term the audience is assumed to know is not a gap.
 6. Check, preview, then hand off:
    - For API docs, every item in
      [Content Standards](/guides/contributing/writing-documentation/writing-api-docs.md#content-standards),
+     including a `@summary` on each exported symbol or `@module` comment you add or touch that
+     owns an API page (not on class members), since it is that page's only `llms.txt`
+     description, per
+     [Give Each API Page a `@summary`](/guides/contributing/writing-documentation/writing-api-docs.md#give-each-api-page-a-summary),
      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>
@@ -69,6 +87,15 @@ last two bullets: the checks and the label.
      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).
+     When that means moving prose out of a README, remove only the sections the other page now
+     owns. The README keeps everything
+     [README structure](/guides/contributing/writing-documentation/writing-api-docs.md#readme-structure)
+     lists: its introduction and, for a legacy package, the alert naming the replacement; the
+     install line and one elevator-pitch snippet, which the landing page is meant to repeat in
+     more depth; and every branding block, the tagline and the `♥️ Credits` block with its style
+     tag.
+     [Keep READMEs short](/guides/contributing/writing-documentation/writing-api-docs.md#keep-readmes-short)
+     says why.
    - 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
@@ -77,7 +104,7 @@ last two bullets: the checks and the label.
 
 ## Gotchas
 
-All three are explained in the
+The first 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

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

@@ -26,11 +26,18 @@ of any `emberjs/rfcs` number:
    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
+3. Review the draft for terseness and conciseness before opening the PR, and again after every
+   edit to it. Reviewers, and later implementers, read an RFC to learn what the public behavior
+   will be and why; anything else in it costs them time and can drift from the implementation
+   that ships. Omit internal implementation details unless they affect observable public
+   behavior, and where they do, describe the effect in brief rather than the mechanism. Keep
+   historical exposition minimal: enough to motivate the change, not a chronicle of how the
+   current behavior came to be.
+4. 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
+5. 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.
 

package/skills/docs/_meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Docs",
+  "items": ["read-the-docs-as-markdown"],
+  "files": {
+    "read-the-docs-as-markdown": { "title": "Read the Docs as Markdown" }
+  }
+}

package/skills/docs/read-the-docs-as-markdown.md

@@ -0,0 +1,40 @@
+# Read the Docs as Markdown
+
+Use this skill whenever you need something from WarpDrive's guides, upgrade notes, or API
+reference that no other skill covers: a concept, a config option, a signature, a deprecation.
+The published site at `https://warp-drive.io` serves every page as plain Markdown, so you never
+have to read or scrape its HTML.
+
+## Steps
+
+1. Fetch `https://warp-drive.io/llms.txt`. It is the table of contents: one absolute link per
+   page, grouped by section, with the page title as the link text and, where the page provides
+   one, a one-line description after a colon. Pick the one or two pages that match your task and
+   fetch only those.
+2. Fetch the page. Every link in `llms.txt` already ends in `.md` and returns raw Markdown. To
+   reach a page from any other URL you were given, append `.md`:
+   `https://warp-drive.io/guides/the-manual/requests/builders` becomes
+   `https://warp-drive.io/guides/the-manual/requests/builders.md`. If the URL ends in `/`, drop the slash
+   first (`/guides/installation/` becomes `/guides/installation.md`) or append `index.md`; both
+   exist.
+3. Resolve links inside a page against `https://warp-drive.io`. Cross-references in the Markdown
+   are root-relative and already end in `.md`, such as
+   `/guides/the-manual/schemas/resources/legacy-mode.md`, so following one is the same fetch with
+   no guessing. The `url:` line in each page's opening `---` block is the canonical URL to cite.
+4. Read the site's Markdown extensions as what they render to:
+   - `:::tip`, `:::info`, `:::warning`, or `:::danger` through the closing `:::` is a callout box.
+     Text on the opening line is the box's title.
+   - `:::tabs` through `:::` holds alternatives. Each `== Label` line starts one tab. When the
+     labels are frameworks or package managers, read only the tab that matches the app you are
+     working in.
+   - `::: code-group` through `:::` is the same for code: the `[Label]` after each fence's
+     language names its tab.
+   - Comments like `// [!code focus]` or `// [!code ++]` inside a fence are highlighting hints for
+     the website. Ignore them; they are not part of the code.
+5. Reach for `https://warp-drive.io/llms-full.txt` only when you need the whole corpus at once. It
+   concatenates every page, is a few megabytes, and each page in it opens with the same `---` /
+   `url:` block, so you can still tell which page a passage came from. `llms.txt` plus one page is
+   almost always enough.
+
+Both `warp-drive.io` and `https://canary.warp-drive.io` are built from the repository's `main`
+branch; canary is redeployed on every merge and production on demand, so canary may be newer.

package/skills/index.md

@@ -10,6 +10,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` |
+| Look up a guide, upgrade note, or API reference page that no row above covers — a concept, an option, a signature | `docs/read-the-docs-as-markdown.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

@@ -19,6 +19,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) |
+| Look up a guide, upgrade note, or API reference page that no row above covers — a concept, an option, a signature | [Read the Docs as Markdown](/skills/docs/read-the-docs-as-markdown.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