nk_jtb 0.25.0 → 0.26.0

package/.ai/prompts/create-component.md

@@ -4,8 +4,10 @@ Invoke the `jtb-layouts-and-structures` skill before starting.
 
 ## Output
 
-Check `index.html` — if it contains no meaningful content, write there. If it
-already has content, ask whether to add to it or create a new file.
+Check `index.html`.
+
+- If it contains no meaningful content, write there.
+- If it already has content, ask whether to add to it or create a new file.
 
 ## Design Reference
 
@@ -13,7 +15,7 @@ already has content, ask whether to add to it or create a new file.
 
 ## Responsive Behaviour
 
-[Describe how this should adapt, or leave blank and Claude will ask.]
+[Describe how this should adapt, or leave blank for ai to ask.]
 
 ## Target Markup
 
@@ -23,9 +25,15 @@ already has content, ask whether to add to it or create a new file.
 
 After building, report only actionable items:
 
-- **Issues** — anything that couldn't be expressed cleanly. State the problem
-  and what workaround was used.
-- **Recommendations** — patterns or utilities that would have made the build
-  cleaner. Flag as candidates worth considering.
-
-Do not report clean decisions or resolved choices.
+- **Issues** — anything that could not be expressed cleanly in JTB. State the
+  problem and what workaround was used.
+- **Framework Gaps** — utilities, tokens, patterns, or primitives that seem
+  missing, weak, or awkward.
+- **Guideline Gaps** — places where the component-creation guidance or JTB docs
+  were unclear or insufficient.
+- **Skill Gaps** — places where the invoked skill was unclear, insufficient,
+  misleading, or failed to help with a relevant decision.
+- **Recommendations** — concrete, minimal changes worth considering.
+
+Do not report clean decisions or resolved choices unless they expose a real
+problem.

package/.ai/prompts/create-documentation.md

@@ -1,7 +1,20 @@
-Create documentation for the `[component].scss` component, following the conventions and architecture rules defined in the JTB documentation.
+Create documentation for `[component]`.
 
-Invoke the `jtb-documentation` skill before starting. Read these in full first
-— these define what is correct:
+Invoke the `jtb-documentation` skill before starting.
 
-- `introduction.md`
-- `docs/conventions-and-architecture-rules.md`
+## Type
+
+[Component / Utility]
+
+## What it does
+
+[One or two sentences describing purpose — not implementation.]
+
+## Cover
+
+[List specific sections or aspects to document, e.g. basic usage, modifiers,
+SCSS variables, utility examples.]
+
+## Notes
+
+[Optional: existing markup, decisions already made, related components.]

package/.ai/prompts/jtb-code-review.md

@@ -1,6 +1,6 @@
 Review the code changes for the NK JTB SCSS framework.
 
-Invoke the `jtb-documentation` skill before starting.
+Invoke the `scss-engineer` and `jtb-documentation` skills before starting.
 
 ## Guidelines
 

package/.ai/prompts/jtb-review-documentation.md

@@ -1,23 +1,20 @@
 Review the documentation for the JTB framework.
 
-Invoke the `jtb-documentation` skill before starting. Read these in full first
-— these define what is correct:
+Invoke the `jtb-documentation` skill before starting. Read these in full first — they define what is correct:
 
 - `introduction.md`
 - `docs/conventions-and-architecture-rules.md`
 
 ## Goals
 
-1. Validate what exists — is documentation correct, consistent, and
-   rule-compliant?
-2. Identify what's missing — what is absent but expected?
+1. Validate what exists — correct, consistent, and rule-compliant?
+2. Identify what's missing — absent but expected?
 
 ## Process
 
-This review runs in three passes:
+Three passes:
 
-1. **Identify** — surface contradictions and gaps. Incomplete docs are expected;
-   flag them without treating incompleteness as a failure.
+1. **Identify** — surface contradictions and gaps. Flag incompleteness without treating it as failure.
 2. **Triage** — decide what's worth pursuing before any work happens.
 3. **Sweep** — act only on approved items.
 
@@ -30,64 +27,40 @@ Review only:
 
 Do not review:
 
-- `src/mixins/` — build system internals
-- `src/functions/` — build system internals
-- `src/base/` — output layer
+- `src/mixins/`, `src/functions/`, `src/base/` — build system internals and output layer
 
 ## Review Questions
 
 ### Validation
 
-1. Do the variable files in `src/maps_and_variables/` match what the
-   conventions doc describes?
+1. Do variable files in `src/maps_and_variables/` match what the conventions doc describes?
 2. Do all final maps follow the `-map` suffix rule?
-3. Is the three-map pattern applied consistently across all variable files?
+3. Is the three-map pattern applied consistently?
 4. Is `smart-merge` order correct — variants first, values second?
-5. Are `!default` flags present where the conventions require them?
-6. Do the breakpoint values in `_base.scss` match what `responsive-design.md`
-   describes?
+5. Are `!default` flags present where required?
+6. Do breakpoint values in `_base.scss` match `responsive-design.md`?
 7. Does `index.scss` forward all expected files?
 
-### Gap Identification
+### Gaps
 
 1. Are there variable files with no corresponding documentation?
-2. Are there conventions described in the docs with no implementation in
-   `src/maps_and_variables/`?
+2. Are there conventions with no implementation in `src/maps_and_variables/`?
 
-## Priority Definitions
+## Priorities
 
-- `critical` — contradicts a source of truth or produces incorrect guidance.
-  Must fix.
-- `high` — likely causes confusion, inconsistency, or future breakage. Should
-  fix.
-- `low` — style, preference, or minor improvement. Fix if you want.
+- `critical` — contradicts a source of truth. Must fix.
+- `high` — likely causes confusion or future breakage. Should fix.
+- `low` — minor improvement. Fix if you want.
 - `missing` — expected content that isn't there.
 
-## Output Requirements
+## Output
 
-- Be direct and critical.
-- Do not praise unnecessarily.
-- Separate findings by type clearly.
-- Suggest improvements with trade-offs.
-- If something is unclear or inconsistent, call it out explicitly.
+Be direct. Do not praise. Call out anything unclear or inconsistent.
 
-Write results to `review-docs-run1.md` in the project root.
-
-Use these sections in order:
-
-- **Confirmed Issues** — rule violations, bugs, mismatches
-- **Gaps** — missing docs, tests, examples, or conventions
-- **Findings** — observations that don't rise to issues
-- **Pass** — if no confirmed issues: `No blocking issues found.`
-
-For every confirmed issue use this format:
+Write results to `review-docs.md` in the project root using these sections:
 
+**Confirmed Issues** — rule violations, bugs, mismatches
 **Issue title** · `critical/high/low`
 `file:line`
 Rule: brief quote
-Fix: one line
-
-For every gap use this format:
-
-**Gap title** · `missing`
-What's absent and where it's expected.
+Fix: on

package/.ai/skills/jtb-conversion/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: jtb-conversion
 description: >-
-  Use this skill whenever applying or converting to NK JTB classes and
-  components, regardless of the source — Tailwind, custom CSS, plain HTML,
-  PHP, JS, or any other context. Do not wait for an explicit request — if JTB
-  classes or components are being applied or converted, this skill applies.
+  Use this skill whenever translating an existing implementation into NK JTB
+  classes and components — for example from Tailwind, custom CSS, plain HTML,
+  PHP, JS, or another framework. Do not wait for an explicit request — if
+  there is a source implementation that needs to be converted into JTB, this
+  skill applies.
 ---
 
-For layout decisions during conversion, invoke the `jtb-layout` skill.
+Do not use this skill for greenfield JTB component builds, design-to-code work
+from screenshots/mockups, or general component composition from scratch.
+
+For layout decisions during conversion, invoke the
+`jtb-layouts-and-structures` skill.
 
 If the output file is not specified, ask before proceeding.
 

package/.ai/skills/jtb-documentation/SKILL.md

@@ -6,6 +6,23 @@ description: >-
   updated, this skill applies.
 ---
 
+Extends `nk-documentation-best-practices` — apply both, this skill takes
+precedence where they conflict.
+
+## Nav Management
+
+Nav lives in `scripts/jtb-nav.json`. Route names follow `docs.jtb.{path}`:
+
+- `docs/components/list.md` → `docs.jtb.components.list`
+- `docs/variable-system.md` → `docs.jtb.variable-system`
+
+Add a new entry to the appropriate group when a doc is confirmed complete.
+
+## Completion Follow-Through
+
+- Add confirmed doc to `scripts/jtb-nav.json`.
+- Update the relevant row in `docs/jtb-status.md`.
+
 ## Documentation Locations
 
 - **All documentation** → `docs/`
@@ -13,128 +30,74 @@ description: >-
 ## Workflow
 
 - Create new documentation directly in `docs/`.
-- Mark every new heading with `(review)` until its content is confirmed.
-- When you update a section carrying `(review)`, ask: "[Section name] has been
-  updated. Is this section complete?"
-- On confirmation: remove the `(review)` tag. If the confirmed section is in a
-  component or utility doc (not a skill, reference doc, or api doc), ask: "Do
-  you want this added to a showcase?"
+- On section confirmation: if the section is in a component or utility doc (not
+  a skill, reference doc, or api doc), ask: "Do you want this added to a
+  showcase?"
 - If yes, add it to the appropriate showcase file before moving on.
-- Leave `(review)` on any headings that are still unresolved.
 
 ## Showcases
 
-Showcases are quick visual references — not comprehensive docs. There are three
-showcase files:
+Showcases are quick visual references — not comprehensive docs. Three files:
 
 - `docs/showcase-typography.md` — font sizes, weights, families, text utilities
-- `docs/showcase-ui.md` — components and UI elements: buttons, badges,
-  checklist, box etc.
+- `docs/showcase-ui.md` — components and UI elements: buttons, badges, checklist, box etc.
 - `docs/showcase-layouts.md` — grid, flex patterns, page structures
 
 Two reasons something belongs in a showcase:
 
 1. **Syntax reminder** — enough variations exist that you forget the class names
-   (border, typography)
-2. **Existence reminder** — a single component worth flagging so it doesn't get
-   overlooked (checklist)
+2. **Existence reminder** — a single component worth flagging so it doesn't get overlooked
 
-Showcase entries have no explanation — just enough to jog memory. Format depends
-on content type:
+Format depends on content type:
 
-- **UI components** (`showcase-ui.md`) — use `+demo-folded` so markup is visible
-  and copyable
-- **Typography/syntax** (`showcase-typography.md`) — use raw HTML pairing
-  `<code>` class names with output
+- **UI components** (`showcase-ui.md`) — use `+demo-folded` so markup is visible and copyable
+- **Typography/syntax** (`showcase-typography.md`) — raw HTML pairing `<code>` class names with output
 - **Layouts** (`showcase-layouts.md`) — case by case
 
-Group entries by component family under `##` headings (e.g. `## Lists`, `##
-Buttons`). Individual variants sit under `###` within that group.
+Group by component family under `##` headings. Variants sit under `###` within that group.
 
-Do not create a new showcase file for a single component — if it doesn't fit the
-three above, discuss with the user.
+Do not create a new showcase file for a single component — if it doesn't fit the three above, discuss with the user.
 
 ## Documentation Types
 
-Choose the document shape based on what is being documented.
-
 ### Utility Documentation
 
-Use for class-based APIs such as spacing, sizing, border, position, transforms,
-and typography helpers.
+Use for class-based APIs such as spacing, sizing, border, position, transforms, and typography helpers.
 
-Default structure:
+Structure:
 
-1. Title
-2. One-line lead
-3. Major utility groups as `##` headings when the page covers more than one
-   family
-4. Example groups within those sections as `###` headings when needed
-5. Optional compact table of available properties or value groups
-6. Available values at the end, when useful
+1. Major utility groups as `##` headings when the page covers more than one family
+2. Example groups within those sections as `###` headings when needed
+3. Optional compact table of available properties or value groups
+4. Available values at the end, when useful
 
 Rules:
 
-- Let the examples do most of the work.
-- Keep prose short.
-- Use `##` for major utility families such as `Border` and `Outline` when the
-  page covers multiple related groups.
-- Use `###` for example groups within those families such as `Width`, `Color`,
-  `Style`, or `Offset`.
-- Keep utility heading levels parallel. Do not mix levels unevenly when the
-  groups are peers.
+- Keep utility heading levels parallel.
 - Use a compact table near the top when it helps scan the utility API quickly.
 - Only add notes when behaviour is non-obvious.
-- Keep review notes, implementation commentary, and TODOs out of the main doc.
 - Group examples by usage, not by SCSS implementation detail.
 - Use `+demo-folded class="bx"` for interactive examples.
-- Use `preview-class="..."` for visual aids in the docs so they do not affect
-  the code being copied.
-- Use `class="..."` for the outer demo wrapper when the preview needs a
-  container such as `bx`.
+- Use `preview-class="..."` for preview-only layout so copied code stays clean.
+- Use `class="..."` for the outer demo wrapper when the preview needs a container such as `bx`.
 
 ### Component Documentation
 
-Use for named structural classes such as `navbar`, `menu`, `bx`, or form
-controls.
+Use for named structural classes such as `navbar`, `menu`, `bx`, or form controls.
 
-Every component doc must communicate four things — heading names can flex to
-suit the content:
+Every component doc must cover:
 
-1. **What it is** — a one-line lead describing purpose, not implementation
-2. **How to use it** — minimum working markup shown early with `+code`
-3. **What it looks like** — examples moving from simple to fuller usage
-4. **How to customise it** — variables, modifiers, or overrides
+1. What it is — one-line lead
+2. Minimum working markup — shown early with `+code`
+3. Examples — simple to fuller usage
+4. Customisation — variables, modifiers, or overrides
 
 Rules:
 
-- Do not add a separate `## Introduction` heading — the lead is the
-  introduction.
-- The lead describes what the component is and does — not implementation
-  details. Do not mention specific CSS properties. Those may change; the
-  component's purpose does not.
-- Heading names should match the content. A single component might use `##
-  Structure` and `## Basic Usage`. A page covering base styles and variants
-  might use `## Base` and `## Variants`. Use whatever is clearest.
-- Show the minimum working structure early with `+code`.
-- Use prose where structure or context-aware behaviour needs explanation.
-- Move from simple usage to fuller examples.
-- Wrap all interactive examples in `class="bx"` on the demo block so they are
-  visually presented in context.
-- Include an SCSS Variables table when the component exposes overridable
-  variables. Link to `/docs/jtb/variable-system` for override instructions
-  rather than explaining inline.
-- Include a `## Utility Examples` section when a utility-based approach to the
-  same pattern is viable. This lives in the component doc — not a separate
-  file. It shows the utility-built version alongside the component class.
-
-## Prose vs Code
-
-Default to code-first. Add prose only when:
-
-- Context-aware behaviour needs explanation
-- Non-obvious structure requires a note
-- Foundational patterns apply across multiple examples
+- The lead describes purpose, not implementation. Do not mention specific CSS properties.
+- Wrap all interactive examples in `class="bx"`.
+- Include an SCSS Variables table when the component exposes overridable variables. Link to `/docs/jtb/variable-system` for override instructions rather than explaining inline.
+- Include a `## Utility Examples` section when a utility-based approach is viable. Lives in the component doc — not a separate file.
 
 ## Code Block Attributes
 
@@ -142,33 +105,20 @@ Default to code-first. Add prose only when:
 - `preview-class="..."` → class applied to the preview container
 - `+demo` / `+demo-folded` → render preview and code together
 
-Prefer `preview-class` when the layout is only for the preview. That keeps the
-example code cleaner when copied.
-
-For layout/responsive docs, use `class="resizable-container
-with-docs-only-overrides"` so the example preview can respond inside the docs
-without changing the copied markup.
+For layout/responsive docs, use `class="resizable-container with-docs-only-overrides"`.
 
 ## Links
 
-Docs are served from a Laravel app. Always use app-rooted paths — never relative
-file paths:
+Docs are served from a Laravel app. Always use app-rooted paths:
 
 - `/docs/jtb/variable-system` ✅
 - `../variable-system.md` ❌
 
-The base path is `/docs/jtb/` followed by the directory and filename without
-extension — mirroring the `docs/` folder structure:
+Base path is `/docs/jtb/` + directory and filename without extension:
 
 - `docs/components/list.md` → `/docs/jtb/components/list`
-- `docs/api/helpers.md` → `/docs/jtb/api/helpers`
 - `docs/variable-system.md` → `/docs/jtb/variable-system`
 
 ## Formatting Rules
 
-- **No horizontal rules (`---`)** — ever. Use headings and spacing
-- **Concise** — get to the point
-- **Show code** — examples over explanation
-- **Document the non-obvious** — skip what's clear from context
-- **Call out outstanding review tags** — when closing documentation work, say
-  which headings or docs still carry `(review)` tags
+- **No `<hr>` in demo markup** — never use horizontal rules in examples

package/.ai/skills/jtb-layouts-and-structures/SKILL.md

@@ -11,6 +11,7 @@ For layout or responsive work, read:
 
 - `docs/responsive-design.md`
 - `docs/layouts-and-structures.md`
+- `docs/magic-classes.md`
 
 ## Scope
 
@@ -34,8 +35,11 @@ Do not use this skill for general documentation or for framework-internals work.
    - `grid` with `cols-*` for column-based structures
    - `flex` for linear, single-axis arrangements
    - `container-*` for width and placement
-3. Build mobile-first. Add responsive enhancements with `{bp}:` prefixes.
-4. Only escalate to custom solutions when documented primitives cannot express
+3. Check whether JTB already provides an approved magic or composite class that
+   reduces responsive noise for the pattern you need.
+4. Build mobile-first. Add explicit `{bp}:` responsive utilities only when no
+   documented higher-level pattern expresses the layout cleanly.
+5. Only escalate to custom solutions when documented primitives cannot express
    the need cleanly.
 
 ## Markup
@@ -45,6 +49,13 @@ Do not use this skill for general documentation or for framework-internals work.
 ## Rules
 
 - Prefer mobile-first base layouts with responsive enhancement.
+- Default to the fewest structural elements that cleanly express the layout.
+- Combine width, rhythm, and internal layout on the same element when they do
+  not need isolation.
+- Do not split `container`, padding, and grid/flex across extra wrappers unless
+  one of those concerns genuinely needs its own box.
+- Put shared layout/presentation utilities on the highest valid parent. Only
+  repeat them on children when a child genuinely needs a different value.
 - Treat `container-*` as a layout primitive with built-in inline gutter. Do not
   add extra horizontal padding on the same element.
 - Let the component own its internal padding. Use the container for width and
@@ -52,5 +63,8 @@ Do not use this skill for general documentation or for framework-internals work.
 - Default section rhythm:
   - `py-4-3-2` for standard sections
   - `py-5-3-2` for more prominent sections
+- Prefer approved magic/composite classes when they express an established
+  responsive pattern more clearly than explicit breakpoint chains. Common
+  examples include `py-*`, `gap-*`, and `cols-*` patterns.
 - Use `{bp}:` for progressive layout changes.
 - Use `to-` and `on-` primarily for visibility windows, not layout progression.

package/AGENTS.md

@@ -85,7 +85,8 @@ use `gap` instead.
 
 **Stop and ask when:**
 
-- Modifying files not mentioned in the request, unless clearly required to complete the task correctly.
+- Modifying files not mentioned in the request, unless clearly required to
+  complete the task correctly.
 - Multiple valid approaches exist and the choice has real consequences.
 - Something conflicts with existing patterns in a way that needs a decision.
 - Your interpretation of the request is genuinely ambiguous.
@@ -95,13 +96,15 @@ use `gap` instead.
 - "I'll also…" — unsolicited additions
 - "While I'm at it…" — scope expansion
 - Using flags, options, or commands not present in the existing code or docs
-- Expanding scope because something "requires" it — name the prerequisite and
-  ask first
+- Expanding scope because something "requires" extra work — name the
+  prerequisite and ask first
 
 ## Assumptions
 
-If proceeding depends on an assumption, state it plainly. If the assumption
-has real consequences, stop and ask instead.
+State assumptions plainly. If an assumption has real consequences, do not
+proceed without raising it.
+
+If you are not sure, say so directly. Do not present guesses as facts.
 
 ## Disagreement and Pushback
 
@@ -130,13 +133,40 @@ follow the direction.
 - **Name it before fixing it** — if something needs prerequisite work, say what
   and why before doing it
 
-## Behaviour
-
-- Do not add adjacent improvements, refactors, or cleanup unless explicitly
-  requested or clearly required to complete the task.
-- Do not bundle unrelated cleanup, renaming, formatting changes, or
-  reorganisation into the requested task unless asked or required.
-- If you are not sure, say so directly. Do not present guesses as facts.
+## Consistency First
+
+- Check what the codebase already does before applying any rule or pattern.
+- Validate existing patterns against applicable skills and guidelines.
+- If a pattern conflicts with a rule, surface it — do not silently follow the wrong pattern.
+
+## Scope Discipline
+
+- Do not add adjacent improvements, refactors, cleanup, renaming, formatting,
+  reorganisation, or bundled unrelated changes unless explicitly requested or
+  clearly required to complete the task correctly.
+- Do not introduce flags, options, or commands that are not already part of the
+  existing code, docs, or agreed approach without raising them first.
+- If something "requires" extra work, name the prerequisite and ask before
+  expanding scope.
+- Never remove a non-obviously-wrong comment without explicit approval.
+
+## Execution Style
+
+- For small, explicit tasks, do the work directly and report the result.
+- For multi-step, risky, or ambiguous work, use incremental check-ins.
+- Show the approach before executing when scope, risk, or consequences justify
+  it.
+- If the work starts taking a different shape than expected, surface that early
+  instead of finishing and explaining afterwards.
+- Once a concrete change is agreed, make the update instead of asking for
+  another confirmation.
+- Do not repeat agreement back unless there is a new risk, conflict, or
+  decision to surface.
+- Keep responses concise. Avoid long explanations when the next action is
+  already clear.
+- Do not summarise completed work. The result speaks for itself.
+- Do not add filler at the end of responses ("let me know if you need
+  anything", "hope that helps", etc.).
 
 ## Frustrations to Avoid
 
@@ -146,39 +176,64 @@ follow the direction.
 - Burying a concern in the middle of a response instead of leading with it
 - Being indirect or vague to avoid conflict
 
-## Iteration Style
-
-- For multi-step, risky, or ambiguous work — use incremental check-ins.
-- For small, explicit tasks — complete the work directly and report the result.
-- Show the approach before executing when the scope, risk, or consequences justify it.
-- If something is taking a different shape than expected, surface it early
-  rather than finishing and explaining after.
+## Session Management
+
+- Work one issue at a time. Do not answer several unresolved points in a single
+  response.
+- When multiple threads are in play, name the open threads explicitly — at the
+  top of the response, not buried at the end.
+- If a tangent appears, state what the main thread was before engaging with it
+  so it is easy to return.
+- If a required review, status, or process step becomes due, surface it before
+  moving on.
+
+## Naykel Conventions
+
+- When reviewing guidelines, skills, or conventions in a Naykel project, assume
+  they apply across all Naykel projects unless explicitly marked as
+  project-specific. Do not treat them as local decisions without evidence.
+
+## Skills and File References
+
+- When a skill system is available and a skill applies, invoke it before
+  proceeding unless it conflicts with the user's explicit request.
+- Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
+- When updating prompts, guidelines, or skills, first identify the project's
+  source-of-truth file before editing.
+- Files under `.ai/` may be symlinks into a shared prompts/guidelines repo. If
+  so, update the symlink target.
+- Do not update matching copies in parallel or alternate locations unless they
+  are the confirmed source of truth or the user explicitly asks.
+- After changing project guidelines or adding/updating skills, run
+  `php artisan boost:update` in the project so the changes take effect.
+- When a skill or prompt references a file that cannot be read, first try
+  resolving it from the repository root.
+- If the file still cannot be found, stop and ask before proceeding.
+- Do not make assumptions in place of missing references.
+- Reference files and code locations using markdown links:
+  `[filename.md](path/to/file.md)` or `[file.php:42](path/file.php#L42)`.
+  Never use plain text paths.
 
-## Skills
-
-When a skill system is available and a skill's trigger condition matches the
-current task, invoke the skill before proceeding unless it conflicts with the
-user's explicit request. Do not read SKILL.md files directly as a substitute
-for invocation — reading is not the same as invoking.
+## Task Tracking
 
-## File References
+`tasks.md` in the project root is a memory aid. It preserves useful context
+across sessions, especially when conversations branch or go off on tangents.
 
-When a skill or prompt references a file that cannot be read, first try
-resolving the path from the repository root. If it
-still can't be found, stop and ask before proceeding. Do not make assumptions
-in place of missing information.
+**What belongs:**
 
-## Task Tracking
+- Specific findings or decisions that would otherwise be lost
+- Items discussed but not being worked on right now
+- Durable context worth remembering later
 
-`tasks.md` in the project root is a memory aid — it keeps work on track and
-preserves important context across sessions.
+**What does not belong:**
 
-**What belongs:** specific findings or decisions from a conversation that would
-otherwise be lost. These are things often identified when going off on tangents
-or having multiple topics on the go at once.
+- Status of active work
+- Things Nathan obviously knows
+- Vague reminders
+- Obvious next steps
 
-**What does not belong:** status of active work, things Nathan obviously knows,
-vague reminders, obvious next steps.
+Write to `tasks.md` when a decision, finding, or parked item would otherwise
+be lost at the end of the session. Do not wait to be asked.
 
 Three buckets:
 
@@ -188,5 +243,5 @@ Three buckets:
 
 ## Off-Limits Directories
 
-- **`/tmp`** — Nathan's personal scratch space. Never read, modify, delete, or
-  reference files here unless explicitly asked.
+- `/tmp` is Nathan's personal scratch space. Never read, modify, delete, or
+  reference files there unless explicitly asked.