nk_jtb 0.25.1 → 0.26.0

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-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/AGENTS.md

@@ -133,6 +133,12 @@ follow the direction.
 - **Name it before fixing it** — if something needs prerequisite work, say what
   and why before doing it
 
+## 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,
@@ -142,6 +148,7 @@ follow the direction.
   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
 
@@ -157,6 +164,9 @@ follow the direction.
   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
 
@@ -168,24 +178,41 @@ follow the direction.
 
 ## Session Management
 
-- Keep track of the main topic, current focus, queued items, parked tangents,
-  and open process steps throughout the session.
 - Work one issue at a time. Do not answer several unresolved points in a single
   response.
-- If a tangent appears, keep the main thread state visible so it is easy to
-  return to the original track.
-- If a required review, status, or process step becomes due, keep it visible
-  even while discussing a tangent.
+- 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.
 
 ## Task Tracking
 
@@ -205,6 +232,9 @@ across sessions, especially when conversations branch or go off on tangents.
 - 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:
 
 - **Planned** — specific actionable items not being worked on right now

package/CLAUDE.md

@@ -133,6 +133,12 @@ follow the direction.
 - **Name it before fixing it** — if something needs prerequisite work, say what
   and why before doing it
 
+## 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,
@@ -142,6 +148,7 @@ follow the direction.
   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
 
@@ -157,6 +164,9 @@ follow the direction.
   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
 
@@ -168,24 +178,41 @@ follow the direction.
 
 ## Session Management
 
-- Keep track of the main topic, current focus, queued items, parked tangents,
-  and open process steps throughout the session.
 - Work one issue at a time. Do not answer several unresolved points in a single
   response.
-- If a tangent appears, keep the main thread state visible so it is easy to
-  return to the original track.
-- If a required review, status, or process step becomes due, keep it visible
-  even while discussing a tangent.
+- 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.
 
 ## Task Tracking
 
@@ -205,6 +232,9 @@ across sessions, especially when conversations branch or go off on tangents.
 - 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:
 
 - **Planned** — specific actionable items not being worked on right now

package/docs/installation.md

@@ -16,7 +16,7 @@ npm install nk_jtb
 
 ## Configure (review)
 
-Override variables before importing. See [Customisation](customisation.md) for
+Override variables before importing. See [Variable System](/docs/jtb/variable-system) for
 details.
 
 ```scss +code
@@ -37,4 +37,4 @@ Import only the layers you need:
 @use 'nk_jtb/src/utilities/spacing' as *;
 @use 'nk_jtb/src/utilities/flexbox' as *;
 ```
-
+

package/docs/introduction.md

@@ -124,5 +124,5 @@ The `.btn` class handles structure, padding, transitions, and states. The
 `.primary` theme handles colors for all states and dark mode. Add utilities only
 when you need to override the defaults.
 
-See [Installation](installation.md) to get started.
+See [Installation](/docs/jtb/installation) to get started.