At skill entry, run node docs/.joycraft/check.mjs check --json --session <session-id> once, reusing JOYCRAFT_SESSION_ID if supplied or one ID chosen for this conversation. If the checker is missing or fails, continue the requested skill quietly without retrying setup. Offer updates only for display: true; current, postponed, off, and unknown stay quiet. If automaticUpdate is present, finish this skill, then run its exact command once from the project root: the candidate must verify every safety gate before applying. Other updates require approval. After an offer or automatic attempt, record it with node docs/.joycraft/check.mjs acknowledge <available-version> --session <session-id>. Apply updates only at this workflow boundary; after success, reinvoke the skill or restart the session to load changed instructions.

Add Context

The user wants to author ONE long-form reference doc — a design system, a frontend or backend methodology, testing conventions, or any other long-form reference for this project. Your job is to scaffold that doc from the matching template, fill in what the user has told you, write it immediately, and wire a pointer row into AGENTS.md's ## Context Map.

This is the single-doc primitive. Write-as-you-go is correct here: you scaffold and write ONE doc per invocation, immediately — not a batch.

This skill is self-contained. Everything you need is below; do not call into or import another skill's logic.

Step 1: Determine Topic and Slug

Figure out what reference doc the user wants. If they named it (e.g., /joycraft-add-context our design system), use that. Otherwise ask: "What reference doc do you want to author?" — then wait.

Derive a kebab-case <slug> from the topic (e.g., "our design system" → design-system, "payments service backend" → payments-backend).

Step 2: Pick the Matching Template

Choose the bundled template in docs/templates/context/reference/ that best fits the topic:

If the topic matches none of the four named templates, use the generic reference-doc.md.

Step 3: Scaffold the Doc to docs/context/reference/<slug>.md

1. Lazy-create docs/context/reference/ — create the directory only now, on first write. Do not create it preemptively in projects that never call this skill.
2. Read the chosen template from docs/templates/context/reference/. If that template file isn't present in the project, fall back to a minimal skeleton: an # H1 title, a > purpose blockquote, and one ## section.
3. Copy the template to docs/context/reference/<slug>.md, set the H1 to the real topic, and fill in whatever the user has already told you. Leave the rest of the template's deletable italic examples in place for the author to replace.
4. Write the doc immediately — this single doc, this invocation. Do not defer or batch.

If docs/context/reference/<slug>.md already exists (the user is re-running for the same slug), update it in place rather than creating a duplicate.

Step 4: Add or Update the Context Map Pointer Row (Idempotent)

Read AGENTS.md and maintain a pointer row for this doc in the ## Context Map section. The row format is:

| docs/context/reference/<slug>.md | <when to read it> |

Apply this idempotent logic exactly:

1. If a ## Context Map section does not exist, create it (place it after the project intro / Behavioral Boundaries area, before deep architecture). Add the header and a two-column table:

   ## Context Map
   
   | Doc | When to read it |
   |-----|-----------------|

2. If a row whose first cell is docs/context/reference/<slug>.md already exists, update that row in place (refresh the "when to read it" cell). Do NOT add a second row for the same path.
3. Otherwise, append one new row to the Context Map table.

Never duplicate a row. The Context Map is a lightweight pointer index — one row per reference doc, nothing more.

Step 5: Confirm

Report what you did:

Scaffolded docs/context/reference/<slug>.md from the <template> template.
Context Map row [added | updated]:
  | docs/context/reference/<slug>.md | <when to read it> |

Fill in the doc's sections — the italic examples are placeholders to replace or delete.

Then end with the canonical Handoff block. After authoring a context doc, the next move is usually back to the work at hand; for a first-run onboarding sweep of several docs, point the user at the gather pass.

Recommended Next Steps

Next:

/joycraft-session-end

Run /clear first.