nk_jtb 0.21.0 → 0.23.0

package/.opencode/.markdownlint.json

@@ -0,0 +1,5 @@
+{
+  "MD041": false,
+  "MD024": false,
+  "MD013": false
+}

package/.opencode/DIRECTORY_TYPES.md

@@ -0,0 +1,133 @@
+# OpenCode Directory Types
+
+## Project Structure
+
+```bash +code
+project/
+├── AGENTS.md                 ← Special file (root, no .opencode/)
+├── opencode.json             ← Config file (root)
+└── .opencode/
+    ├── context/             ← Auto-loaded guidelines
+    ├── skills/              ← On-demand skills
+    └── agents/              ← Custom subagents
+```
+
+## Where Config Lives
+
+| File            | Purpose       | How Used                                     |
+| --------------- | ------------- | -------------------------------------------- |
+| `opencode.json` | Main config   | Must be named exactly, references everything |
+| `AGENTS.md`     | Project agent | OpenCode auto-discovers in root              |
+
+## Directory Types
+
+```bash +code
+.opencode/
+├── context/      ← Auto-loaded
+├── skills/      ← On-demand
+└── agents/      ← On-demand
+```
+
+## Context vs Skills vs Agents
+
+|            | Auto-loaded | On-demand | Use When                     |
+| ---------- | ----------- | --------- | ---------------------------- |
+| `context/` | ✓           |           | Guidelines that always apply |
+| `skills/`  |             | ✓         | Task-specific instructions   |
+| `agents/`  |             | ✓         | Specialized workers          |
+
+---
+
+## Context/
+
+General guidelines loaded automatically.
+
+```bash +code
+.opencode/context/
+└── *.md            # Referenced in opencode.json
+```
+
+**When to add:**
+
+- Working preferences (e.g., `working-with-nathan.md`)
+- SCSS conventions (e.g., `scss-guidelines.md`)
+- Team coding standards
+- Framework philosophy
+
+**Example:**
+
+```json +code
+// opencode.json
+{
+  "instructions": [
+    ".opencode/context/scss-guidelines.md",
+    ".opencode/context/working-with-nathan.md"
+  ]
+}
+```
+
+---
+
+## Skills/
+
+Reusable task-specific modules loaded on-demand.
+
+```bash +code
+.opencode/skills/
+└── <name>/
+    └── SKILL.md    # Frontmatter required
+```
+
+**When to add:**
+
+- Language-specific formatting (e.g., `markdown-formatting/`)
+- Tool-specific workflows (e.g., `git-commit/`)
+- Framework patterns (e.g., `laravel-php/`)
+
+**Example SKILL.md:**
+
+```yaml +code
+---
+name: markdown-formatting
+description: Applies markdown conventions with Torchlight tags
+---
+## When to use
+Writing or editing markdown files with Torchlight code blocks.
+```
+
+---
+
+## Agents/
+
+Custom subagents invoked for specialized tasks.
+
+```bash +code
+.opencode/agents/
+└── <name>.md
+```
+
+**When to add:**
+
+- SCSS Engineer (framework-specific work)
+- API Specialist (backend work)
+- Test Writer (test patterns)
+
+**Example:**
+
+```bash +code
+skill({ name: "scss-engineer" })  ← Agent invoked for SCSS tasks
+```
+
+---
+
+## Quick Reference
+
+| Need                        | Place           |
+| --------------------------- | --------------- |
+| Guidelines that always load | `context/`      |
+| Task-specific instructions  | `skills/`       |
+| Specialized worker          | `agents/`       |
+| Main config                 | `opencode.json` |
+| Project agent               | `AGENTS.md`     |
+
+---

package/.opencode/agents/scss-engineer.md

@@ -0,0 +1,169 @@
+# SCSS Engineer Agent
+
+Specializes in JTB framework development, component architecture, and utility generation.
+
+## Scope and Authority
+
+- This agent is for **building/extending JTB internals** (SCSS architecture,
+  maps, mixins, utility generation, components).
+- For **framework usage rules** (responsive semantics, conversion behavior,
+  class mapping contract), follow `AGENTS.md`.
+- This file extends `AGENTS.md` and must not override it.
+
+## Key Conventions
+
+- **Numbers = rem values:** `m-1` = 1rem, `m-05` = 0.5rem (leading zero dropped)
+- **Property = class name:** `relative`, `sticky` (NOT `position-relative`)
+- **Axis modifiers:** `-xy`, `-x`, `-y`, `-t`, `-b`, `-l`, `-r`
+- **Pattern:** `{breakpoint}:{property}-{variant/value}`
+- **NOT Tailwind:** No `position-`, no `-x`/`-y` suffixes for everything
+
+## Expertise
+
+- JTB modular architecture
+- Builder/Maker class generation system
+- Three-map variable pattern
+- Context-aware modifier system
+- Logical properties (RTL support)
+- Stylelint configuration
+
+## Component Workflow
+
+### 1. Add Variables
+
+In `src/maps_and_variables/_components.scss`:
+
+```scss
+$card-padding: 1rem !default;
+$card-bg: #fff !default;
+$card-radius: 0.5rem !default;
+```
+
+### 2. Create Component
+
+In `src/components/_card.scss`:
+
+```scss
+@use '../maps_and_variables/components' as *;
+
+%card {
+    background: $card-bg;
+    border-radius: $card-radius;
+    padding: $card-padding;
+}
+
+.#{$card-prefix} {
+    @extend %card;
+
+    &-header { }
+    &-body { }
+    &-footer { }
+}
+```
+
+### 3. Export
+
+In `src/components/index.scss`:
+
+```scss
+@forward '_card';
+```
+
+## Utility Generation
+
+### Using build-classes()
+
+```scss
+$margin-map: smart-merge($margin-variants, $margin-values);
+
+$props: (
+    margin: (
+        prefix: 'm',
+        values: $margin-map,
+        unit: 'rem',
+        positions: $logical-position-map
+    ),
+);
+
+@include build-classes($props, $responsive: true);
+```
+
+### Using make-single-property-class()
+
+```scss
+@include make-single-property-class(
+    'display',
+    'flex',
+    'flex',
+    $breakpoints: (md, lg)
+);
+```
+
+### Using make-position-based-class()
+
+```scss
+@include make-position-based-class(
+    'padding',
+    1rem,
+    $logical-position-map,
+    'p',
+    null,
+    (md, lg)
+);
+```
+
+## Three-Map Pattern
+
+```scss
+$property-values: (0, 1, 2, 3) !default;
+$property-variants: (auto: auto, base: 1rem) !default;
+$property-map: smart-merge($property-variants, $property-values);
+```
+
+## Documentation
+
+See `jtb-documentation` skill for detailed documentation patterns.
+
+**Key principles:**
+
+- **Only document what exists** (verify in SCSS first)
+- **Utilities:** Progressive complexity with `+demo-folded` and grid layouts
+- **Minimal prose:** Show code, don't explain
+
+## Context-Aware Modifiers
+
+Modifiers require component context:
+
+```html
+<!-- ✅ CORRECT -->
+<div class="bx primary">Themed box</div>
+<button class="btn xs">Small button</button>
+
+<!-- ❌ WRONG -->
+<div class="primary">No component context</div>
+```
+
+## File References
+
+| Purpose           | File                      |
+| ----------------- | ------------------------- |
+| Work in progress  | `docs-for-review/**/*.md` |
+| Finalized docs    | `docs/**/*.md`            |
+| Builder/Maker API | `docs-for-review/api/*.md`|
+| Import order      | `src/build.scss`          |
+
+## Common Tasks
+
+| Task                   | Location                              |
+| ---------------------- | ------------------------------------- |
+| Add spacing utilities  | `src/utilities/_spacing.scss`         |
+| Add component          | `src/components/_name.scss`           |
+| Add theme color        | `src/maps_and_variables/_colors.scss` |
+| Add typography utility | `src/utilities/_typography.scss`      |
+| Configure breakpoints  | `src/maps_and_variables/_config.scss` |
+
+## Linting
+
+```bash
+npm run lint
+```

package/.opencode/context/working-with-nathan.md

@@ -0,0 +1,72 @@
+Here’s a tightened, AI-friendly version that’s very direct and enforces the “stop vs do” rules clearly:
+
+# Working with Nathan
+
+## When to Act vs When to Ask
+
+**Do it without asking when:**
+
+- The task is explicitly requested.
+- The approach is documented in skills or guidelines.
+- You’re following a known pattern from the codebase.
+
+**Stop and ask before proceeding when:**
+
+- Modifying config files not mentioned in the request.
+- Inventing command flags, options, or behavior.
+- Multiple valid approaches exist and I haven't specified which.
+- You're unsure if your interpretation matches my intent.
+- Something feels off or conflicts with existing patterns.
+
+**Red flags = STOP immediately:**
+
+- “I’ll also…”
+- “While I’m at it…”
+- “To make this work, I need to first…”
+- “This requires…”
+- Using commands or options not present in existing code or docs.
+
+*Rule of thumb:* If in doubt, pause and check.
+
+## Code Philosophy
+
+- **Explicit over clever** — Show what’s happening rather than hiding it.
+- **Start small, expand later** — Validate the approach before building out.
+- **Config = WHAT, Code = HOW** — Config defines structure; code defines implementation.
+
+## Frustrations to Avoid
+
+- Overcomplicating simple things.
+- Suggesting solutions I've already rejected.
+- Hiding behavior or trying to "save me work."
+- Making me second-guess solid decisions.
+- Ignoring instructions or being indirect.
+
+## Skill Philosophy
+
+- **Self-contained skills** — Each skill must have all information needed to execute its task.
+- **No external assumptions** — Skills should never rely on context outside themselves.
+
+## Proactive Verification
+
+Always compare your current understanding or implementation with what I have explicitly asked:
+
+- **Highlight differences clearly** - If something doesn't match, show what differs and why
+- **Point out missing steps** - If you notice a relevant gap, suggest adding it
+- **Record discoveries** - Integrate new findings into context automatically
+- **Present in list format** - For clarity, use lists for suggestions and findings
+
+**Example:**
+
+Differences found:
+
+1. You asked for X, but the code does Y
+2. Missing: Z step in the workflow
+
+Suggestion: Add step Z here...
+
+**Do not act unless instructed**, except to highlight differences, missing info, or updates.
+
+Don't just flip flop when I ask something based on my understanding. If you see
+a clear reason to do something different, explain it and get agreement before
+proceeding.

package/.opencode/prompt-code-review.md

@@ -0,0 +1,73 @@
+# Code Review Prompt for NK JTB SCSS Framework
+
+Before reviewing, load and read these files in full:
+
+- `AGENTS.md`
+- `SKILL.md`
+- `scss-engineer.md`
+- `working-with-nathan.md`
+-
+
+You are reviewing code for the NK JTB SCSS Framework. Please follow these
+guidelines:
+
+- **Framework Alignment:** Ensure all code strictly follows the JTB conventions,
+  naming, and architecture as described in the documentation. Do not use
+  Tailwind or other frameworks as reference for implementation details.
+- **Directory Structure:** Verify files are placed in the correct directories
+  (`base`, `components`, `forms`, `utilities`, `mixins`, `functions`,
+  `maps_and_variables`).
+- **Import Rules:** Check that only `@use` and `@forward` are used for imports.
+  `@import` is prohibited.
+- **Component Structure:** Components should provide structure only, not
+  decoration. Styling must be handled by utilities.
+- **Modifiers:** Only use context-aware modifiers (e.g., `.primary`), never
+  component-specific ones (e.g., `.btn-primary`).
+- **Variables:** All values must use variables or maps—no hardcoded values.
+- **Nesting:** No selector nesting deeper than 3 levels.
+- **Override Order:** Confirm the import order: base → components → forms →
+  utilities.
+- **Documentation:** All new or changed code must be documented using the JTB
+  documentation conventions. Drafts go in `docs-for-review/`, finalized docs in
+  `docs/`.
+
+**Review Checklist:**
+
+1. Does the code follow JTB naming, structure, and logical property conventions?
+2. Are all values variable-driven and override-friendly?
+3. Is the code placed in the correct directory and imported in the right order?
+4. Are all prohibited patterns (see AGENTS.md) avoided?
+5. Is documentation provided or updated as required?
+
+Provide clear, actionable feedback. If you suggest changes, reference the
+specific JTB documentation section or rule.
+
+## Skill & Agent File Review
+
+When any of the source-of-truth files are included in the changeset, review them
+for accuracy against the actual codebase:
+
+**Accuracy**
+
+- Do the documented conventions match how the SCSS actually works?
+- Are examples valid and runnable — not invented or outdated?
+- Do file paths, class names, and patterns reflect the real codebase?
+
+**Completeness**
+
+- Are new patterns or workflows introduced in this PR documented?
+- Are deprecated patterns removed or flagged?
+
+**Internal Consistency**
+
+- Do the files agree with each other? Flag any contradictions between
+  `scss-engineer.md`, `SKILL.md`, `AGENTS.md`, and `working-with-nathan.md`
+- Does a change in one file require an update in another?
+
+**Scope Drift**
+
+- Do changes silently expand or restrict the agent/skill scope without clear intent?
+
+**Output Format:**
+List issues grouped by file. For each issue: severity (blocking/suggestion),
+the violated rule, and a suggested fix.

package/.opencode/prompt-review-component-utility.md

@@ -0,0 +1,51 @@
+# JTB Component/Utility Review
+
+Review the menu component.
+
+Before reviewing, load and read these files in full:
+
+- `AGENTS.md`
+- `docs/conventions-and-architecture-rules.md`
+
+## Scope
+
+Review only the named target and its directly related docs/examples.
+
+## Review Questions
+
+1. Is the documentation correct and complete?
+2. Does the code follow JTB rules and conventions?
+3. Does it match the JTB philosophy and architecture rules?
+4. Are there any mismatches between docs and code?
+5. Are there any prohibited patterns from `AGENTS.md` in this target?
+6. Are there target-level bugs/regressions visible?
+
+## Priority Definitions
+
+- `critical` — violates a documented rule or produces incorrect behavior. Must fix.
+- `high` — likely causes confusion, inconsistency, or future breakage. Should fix.
+- `low` — style, preference, or minor improvement. Fix if you want.
+
+## Output Requirements
+
+- Be direct and critical.
+- Do not praise unnecessarily.
+- Separate strengths and weaknesses clearly.
+- Suggest improvements with trade-offs.
+- If something is unclear or inconsistent, call it out explicitly.
+
+Write results to `review-[target].md` in the project root.
+
+Use these sections in order:
+
+- **Confirmed Issues**
+- **Docs-Code Mismatches**
+- **Findings**
+- **Pass** — if no confirmed issues: `No blocking issues found.`
+
+For every issue use this format:
+
+**Issue title** · `critical/high/low`
+`file:line`
+Rule: brief quote
+Fix: one line

package/.opencode/prompt-review-documentation.md

@@ -0,0 +1,110 @@
+# JTB Documentation Review
+
+Review the documentation for the JTB framework.
+
+Load and read these in full first. These define what is correct:
+
+- `introduction.md`
+- `docs/conventions-and-architecture-rules.md`
+
+Also load:
+
+- `AGENTS.md` — intended source of truth, but flag any contradictions with the
+  above.
+
+## Goals
+
+1. Validate what exists — is documentation correct, consistent, and
+   rule-compliant?
+2. Identify what's missing — what is absent but expected?
+
+## Process
+
+This review runs in three passes:
+
+1. **Identify** — surface contradictions and gaps. Incomplete docs are expected;
+   flag them without treating incompleteness as a failure.
+2. **Triage** — decide what's worth pursuing before any work happens.
+3. **Sweep** — act only on approved items.
+
+---
+
+## Scope
+
+Review only:
+
+- `docs/` — all foundational documentation
+- `src/maps_and_variables/` — all variable and configuration files
+
+Do not review:
+
+- `src/mixins/` — build system internals
+- `src/functions/` — build system internals
+- `src/base/` — output layer
+
+---
+
+## Review Questions
+
+### Validation
+
+1. Do the 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?
+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?
+7. Does `index.scss` forward all expected files?
+
+### Gap Identification
+
+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/`?
+
+---
+
+## Priority Definitions
+
+> Priorities are tentative in early passes — they guide triage, not final
+> decisions.
+
+- `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.
+- `missing` — expected content that isn't there.
+
+---
+
+## Output Requirements
+
+- 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.
+
+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:
+
+**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.