@canonical/pragma-cli 0.34.0 → 0.36.0

package/README.md

@@ -1,72 +1,195 @@
 # @canonical/pragma-cli
 
-`pragma` is a command-line tool **and** a Model Context Protocol (MCP) server over Canonical's design-system knowledge graph. A single grammar of capabilities is projected two ways — as CLI commands for humans and as MCP tools for agents — both reading the same local, content-addressed store built from your design-system packs.
+`pragma` answers questions about Canonical's design system from your terminal — and, run as a Model Context Protocol (MCP) server, from your AI agent. The design system ships as a knowledge graph: every block (a component, pattern, or layout), every tier, modifier family, and code standard is a node `pragma` can read. Reads answer offline, from a snapshot compiled into the package — no network, no build.
 
-## Install
+| You want to… | Run |
+|---|---|
+| See every block in the design system | `pragma block list` — all 251, each with its tier |
+| Read a block's full spec — anatomy, modifiers, properties | `pragma block lookup Button` |
+| Find the design system's name for something you already know | `pragma block lookup 'Nav*'` — lookups take names or globs |
+| Know which tier something belongs to | `pragma tier list`, `pragma tier lookup <name>` |
+| Stay consistent with the modifiers that already exist | `pragma modifier list` — 11 families |
+| Check your code against the coding standards | `pragma standard list --category react` |
+| Scaffold a component, package, or application | `pragma create component react <path>` |
+| Ask the graph something the commands don't cover | `pragma graph query "<sparql>"` |
+| Set it up, and check it's healthy | `pragma setup`, then `pragma doctor` |
+| Give your AI agent the same access | `pragma setup mcp` |
+
+The sections below take these in turn.
+
+## From install to first answer
 
 ```bash
-npm install -g @canonical/pragma-cli
+bun add --global @canonical/pragma-cli
+# or: npm install -g @canonical/pragma-cli
 ```
 
-This installs the `pragma` binary: a prebuilt, standalone executable (`dist/pragma`). The package publishes for **Linux x64 only** (`"os": ["linux"]`, `"cpu": ["x64"]`) — other platforms are not yet shipped.
+The package ships compiled JavaScript and runs on **Node.js 22.18+ or 23.6+** (any 24 or later), on any platform Node supports. pragma reads its own `pragma.conf.ts` — and your project's `pragma.config.ts` — through Node's TypeScript type stripping, which is on by default from those versions. Node 23.0–23.5 are excluded deliberately: they satisfy a plain `>=22.18` but predate the 23.x line's own default-on release.
 
-Check your environment and confirm the install:
+Then ask for a component:
 
-```bash
-pragma doctor
+````console
+$ pragma block lookup Button
+## Button
+
+- Tier: ds:apps_launchpad
+
+### Summary
+The **Button** component is an interactive element that allows users to trigger an action.
+
+**Main Use Cases:**
+
+- **Actions:** Trigger an action, such as submitting a form or opening a dialog.
+- **Navigation:** Navigate to a different page or view.
+
+### Guidelines
+### Accessibility
+
+- **Label:** Always provide a clear and descriptive label for the button.
+- **Focus state:** Provide a clear focus state for the button.
+
+⋮
+
+### Anatomy (DSL)
+```yaml
+---
+node:
+  uri: app-launchpad.component.button
+  styles:
+    layout.type: stack
+    layout.direction: horizontal
+    layout.align: center
+    spacing.internal: spacing/inline/small
+    appearance.background: color/background/neutral/default
+    appearance.border: border/style/solid
+    appearance.radius: radius/medium
+    typography.size: typography/paragraph/default
+  edges:
+⋮
 ```
 
-## Quickstart
+### Properties
+- name: label | type: text | optional: false
+- name: variant | type: choice | optional: true
+- name: disabled | type: boolean | optional: true
+- name: loading | type: boolean | optional: true
+````
+
+Abridged — the two cuts are marked `⋮`. The full answer is 83 lines: content-writing guidelines, the rest of the anatomy tree (child nodes with slot names and cardinalities, down to their token bindings), and a link to the classic anatomy reference.
+
+That answer came from the snapshot inside the package. No network, no cache, no project setup — `lookup` and `list` work from the moment the install finishes.
+
+## What the graph knows
+
+What this distribution's graph answers today:
+
+| Ask | Answer |
+|---|---|
+| `pragma block list` | **251** blocks — components, patterns, layouts, and subcomponents, each with its tier |
+| `pragma tier list` | **15** tiers — `global`, `apps` plus nine app tiers, `sites` plus one, `stores`, `documentation` |
+| `pragma modifier list` | **11** modifier families — Importance (Primary/Secondary/Tertiary), Anticipation (Caution/Constructive/Destructive), Criticality, Density, Lifecycle, Mode, Release, Surface, and three more |
+| `pragma standard categories` | **21** code-standard categories — react 16, css 15, lit 13, svelte 12, rust 11, storybook 11, code 10, … |
+| `pragma token list` | **0** — this distribution's graph ships no token entities |
+| `pragma prompt list` | **0** — likewise, no prompt entities |
+
+The two zeroes are real answers: the commands say the store is empty rather than inventing, and stay empty until a pack that ships those entities is configured.
 
 ```bash
 pragma block list
-pragma block lookup Button
-pragma sources status
-pragma sources update
-pragma capabilities
+pragma tier list
+pragma modifier list
+pragma standard categories
+pragma token list
+pragma prompt list
+```
+
+The commands are views over one RDF graph. Anything they don't cover, ask directly — prefixes like `ds:` are bound automatically from the active pack:
+
+```bash
+pragma graph query "SELECT ?s WHERE { ?s a ds:Component }"
 ```
 
-Reads answer from the moment you install: the binary carries a compiled snapshot of the design system, so `block list` and `block lookup` work with no cache and no network. `pragma sources update` rebuilds the store from the live packs named in your `pragma.config.ts`; `pragma sources status` reports which of the two is answering and what it was built from.
+## Find the spec, build from it, check the result
 
-To register pragma with a detected AI harness as an MCP server:
+**Find the spec.** Lookups take a name or a glob — useful when you know roughly what something is called:
+
+```bash
+pragma block lookup 'Nav*'
+pragma tier lookup Global
+```
+
+**Build from it.** The `create` commands scaffold a component, package, or application. They run the `@canonical/summon-*` generator packages directly — those are regular dependencies of this package, so scaffolding works from a clean install. Preview any of them with `--dry-run`:
+
+```bash
+pragma create component react src/components/Button
+```
+
+**Check the result.** List the standards for your stack, then look one up by name for its do/don't code examples:
+
+```bash
+pragma standard list --category react
+```
+
+## Your agent reads the same graph
 
 ```bash
 pragma setup mcp
 ```
 
-See [docs/mcp-integration.md](./docs/mcp-integration.md) for the full MCP surface, and the [command & tool reference](./docs/reference/index.md) for every command and tool.
+This registers pragma as an MCP server (over stdio) with the AI coding tools it detects; `pragma mcp` is the manual entry point. The server projects the same reads and scaffolds as MCP tools, plus a `pragma:{+uri}` resource surface for entity reads. Its handshake tells agents to start with the `capabilities` tool and discover from there, and every mutating tool is plan-first: it returns the plan it would apply, and applies nothing until called again with `confirm: true`.
+
+See [docs/mcp-integration.md](./docs/mcp-integration.md) for the full surface.
+
+## Setup and health
+
+```bash
+pragma setup
+pragma doctor
+```
+
+`pragma setup` is one wizard for the whole environment: your config file, MCP registration, TAB completion, agent skills, and the editor extension. Each installer can configure your home directory (global, the default), this project alone, or both — `--scope project|global|both`, with `--global`/`--local` as shorthands. Preview everything it would write with `pragma setup --dry-run`, or run one installer directly: `pragma setup mcp`, `setup completions`, `setup skills`, `setup lsp`.
 
-## Two planes
+The LSP step installs the Terrazzo extension, and the extension's own log is the fastest way to confirm it took. Open your editor's Output panel, select the `terrazzo-lsp` channel, and look for a startup block like this (timestamps dropped, paths shortened):
 
-pragma is extended along two independent planes:
+```console
+[info] Config loaded from <project>/packages/react/ds-global/terrazzo-lsp.config.json
+[info] Root: <project>/packages/react/ds-global
+[info] Artifacts: <project>/packages/react/ds-global/node_modules/@canonical/design-tokens/dist/tokens.json
+[info] Loaded 781 tokens from 1 artifact
+[info] Global stylesheets: 1 file, 0 declarations
+[info] terrazzo-lsp ready
+```
+
+The token count is the line to read: `terrazzo-lsp ready` says the server started, but a run that loaded 0 tokens resolved its artifact path to nothing and will complete nothing. With tokens loaded, type `color: var(--` in a stylesheet — the design tokens should appear as completions.
 
-- **Data plane — the content.** Your design system is a set of packs listed in `pragma.config.ts` (`packs: [...]`). `pragma sources update` compiles them into the local knowledge graph the read commands query. Point pragma at different packs and every `list` / `lookup` / `sample` command answers from that graph — and until you build them, the reads say so rather than answering from the shipped snapshot.
-- **Behaviour plane — the capabilities.** Every command and MCP tool is one entry in a single capability grammar, projected to both the CLI and the MCP server. The [reference](./docs/reference/index.md) is generated from that grammar, so it can never drift from the code.
+`pragma doctor` checks the environment (Node version, store health, registrations) globally and in this project, and names the next step on every row that has one. `pragma info` shows the version, the configuration in effect, and update status; `pragma upgrade` updates the CLI itself.
 
-## Relationship to summon
+## Point it at your own design system
 
-`@canonical/summon` is a separate scaffolding product. pragma reuses summon's generator core so that its scaffolding commands —
+Your project's `pragma.config.ts` names the packs — design-system data packages — the graph is built from:
 
 ```bash
-pragma create component src/components/Button --framework react
+pragma sources update
+pragma sources status
 ```
 
-— produce output byte-identical to summon's own `component`, `package`, and `application` generators. summon is not a runtime dependency. The binary carries the **component** generator's templates, so `pragma create component` runs from a clean install; `pragma create package` and `pragma create application` read their templates from disk and so refuse from the binary with `UNSUPPORTED` — run those from a source checkout, or use the `summon` CLI.
+`sources update` resolves the configured packs and rebuilds the local store; `sources status` reports which store is answering — the shipped snapshot or your build — and exactly what it was built from. Every `list`, `lookup`, and `sample` command then answers from your graph.
+
+The read surface itself is also data, not code. The distribution's own `pragma.conf.ts`, shipped inside the package, declares every read noun — `block`, `standard`, `tier`, their queries, columns, and detail levels — as configuration. A fork serving a different design system rewrites that one file and gets its own CLI commands and MCP tools without writing any command code. (Two files, deliberately distinct: `pragma.config.ts` is your project's; `pragma.conf.ts` is the distribution's.)
 
-## MCP
+[docs/config-model.md](./docs/config-model.md) explains the configuration layers; [docs/architecture.md](./docs/architecture.md) explains how one set of declarations is projected as both CLI commands and MCP tools.
 
-Run pragma as an MCP server over stdio via `pragma setup mcp` (automatic harness registration) or the manual `pragma mcp` entry point. The server exposes the read and scaffold tools, a `pragma:{+uri}` resource surface for entity reads, whatever workflow prompts the active graph declares (none, for this distribution's current graph), and handshake instructions describing the discovery sequence. Mutating tools are plan-first — they return the plan they would apply until called with `confirm: true`. See [docs/mcp-integration.md](./docs/mcp-integration.md).
+## Reference
 
-## Documentation
+The [command & tool reference](./docs/reference/index.md) is generated from the same declarations the CLI runs, so it cannot drift from the code.
 
 - [Getting started](./docs/getting-started.md)
+- [The design system graph](./docs/design-system.md)
+- [Setup and health](./docs/setup.md)
 - [MCP integration](./docs/mcp-integration.md)
 - [Configuration model](./docs/config-model.md)
 - [Architecture](./docs/architecture.md)
 - [Skills](./docs/skills.md)
-- [Command & tool reference](./docs/reference/index.md)
 - [Changelog](./CHANGELOG.md)
 
-## License
-
-GPL-3.0
+License: GPL-3.0

package/bundled-skills/add-standard/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: add-standard
+description: Create and add a new code standard to the code-standards package
+---
+
+# Add Standard
+
+Create and add a new code standard to the code-standards package.
+
+## When to Use
+
+Use this skill when:
+- "Add a standard for..."
+- "Create a coding standard..."
+- "Document a new convention..."
+- "Add guidance for..."
+
+## Workflow
+
+### 1. Check for Existing Standards
+
+Before creating a new standard, always check if one already exists:
+
+```sparql
+PREFIX cs: <http://pragma.canonical.com/codestandards#>
+
+SELECT ?standard ?description WHERE {
+  ?standard a cs:CodeStandard ;
+            cs:description ?description .
+  FILTER(CONTAINS(LCASE(STR(?standard)), "your-topic"))
+}
+```
+
+Or use lookup:
+```
+sem_lookup(type: "cs:CodeStandard", filters: {"@id": {"$contains": "your-topic"}})
+```
+
+### 2. Determine the Category
+
+List existing categories to find the right fit:
+
+```sparql
+PREFIX cs: <http://pragma.canonical.com/codestandards#>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+
+SELECT ?category ?label ?slug WHERE {
+  ?category a cs:Category ;
+            rdfs:label ?label ;
+            cs:slug ?slug .
+}
+```
+
+**Available Categories:**
+
+| Category | Slug | Description |
+|----------|------|-------------|
+| React | `react` | React component development |
+| CSS | `css` | CSS technical implementation |
+| Styling | `styling` | Design system styling patterns |
+| Code | `code` | General TypeScript standards |
+| Storybook | `storybook` | Storybook documentation |
+| Icons | `icons` | Icon implementation |
+| Packaging | `packaging` | Package structure and exports |
+| Rust | `rust` | Idiomatic Rust development |
+| Git | `git` | Git workflow conventions |
+| TSDoc | `tsdoc` | Documentation conventions |
+| Turtle | `turtle` | RDF/Turtle authoring |
+| UI Blocks | `ui-blocks` | Framework-agnostic capabilities and patterns for UI blocks |
+
+If no existing category fits, create a new one (see Section 5).
+
+### 3. Design the Standard Identifier
+
+Standard identifiers follow a hierarchical compact IRI pattern: `cs:{category}.{domain}.{topic}`
+
+**Pattern:** `^cs:[a-z]+(\.[a-z0-9_]+){2,}$`
+
+**Examples:**
+- `cs:react.component.structure.folder`
+- `cs:css.selectors.namespace`
+- `cs:styling.tokens.creation`
+- `cs:react.hooks.naming`
+
+**Guidelines:**
+- Use lowercase with underscores for multi-word segments
+- Category is always the first segment after `cs:`
+- Be specific but not overly verbose
+- Follow existing naming patterns in the same category
+- Treat the subject IRI as the only canonical identifier
+- Use `cs:name` only for an optional human-readable display title
+
+### 4. Write the Standard
+
+Create a new standard instance in the appropriate data file under `data/`.
+
+**Template:**
+
+```turtle
+cs:category.domain.topic a cs:CodeStandard ;
+    cs:name "Human Readable Title" ;
+    cs:hasCategory cs:category ;
+    cs:description "Clear, concise description of what this standard covers and why it matters." ;
+    cs:do [
+        cs:description "First recommended practice." ;
+        cs:language "typescript" ;
+        cs:code """
+// Example showing the correct approach
+const good = true;
+    """
+    ] ;
+    cs:do [
+        cs:description "Second recommended practice." ;
+        cs:language "typescript" ;
+        cs:code """
+// Another correct example
+const alsoGood = true;
+    """
+    ] ;
+    cs:dont [
+        cs:description "First anti-pattern to avoid." ;
+        cs:language "typescript" ;
+        cs:code """
+// Example showing what NOT to do
+const bad = true;
+    """
+    ] ;
+    cs:dont [
+        cs:description "Second anti-pattern." ;
+        cs:language "typescript" ;
+        cs:code """
+// Another bad example
+const alsoBad = true;
+    """
+    ] .
+```
+
+Each `cs:do` and `cs:dont` is a blank node (`cs:Example`) with structured fields:
+- `cs:description` — What the example demonstrates (required)
+- `cs:language` — Language of the code block, e.g. `"typescript"`, `"rust"`, `"css"`, `"bash"`, `"svg"` (optional, omit when no code)
+- `cs:code` — The code content (optional, omit for description-only examples)
+
+**Required Properties:**
+- subject IRI - Canonical compact identifier
+- `cs:hasCategory` - Reference to a Category instance
+- `cs:description` - What and why (plain text or markdown)
+- `cs:do` - One or more positive examples (blank nodes)
+- `cs:dont` - One or more negative examples (blank nodes)
+
+**Optional Properties:**
+- `cs:name` - Human-readable display title
+- `cs:extends` - Reference to a parent standard this builds upon
+
+### 5. Create a New Category (if needed)
+
+If your standard doesn't fit existing categories:
+
+```turtle
+cs:new_category a cs:Category ;
+    rdfs:label "Category Name"@en ;
+    rdfs:comment "Description of what this category covers"@en ;
+    cs:slug "slug-name" .
+```
+
+### 6. Extending Existing Standards
+
+When your standard builds on another:
+
+```turtle
+cs:react.component.props.special_case a cs:CodeStandard ;
+    cs:name "React Props Special Case" ;
+    cs:extends cs:react.component.props ;
+    cs:hasCategory cs:react ;
+    cs:description "Specific guidance that builds on the general props standard." ;
+    cs:do [
+        cs:description "Example of the specific pattern." ;
+        cs:language "typescript" ;
+        cs:code """
+// ...
+    """
+    ] ;
+    cs:dont [
+        cs:description "Anti-pattern to avoid." ;
+        cs:language "typescript" ;
+        cs:code """
+// ...
+    """
+    ] .
+```
+
+Query to find potential parent standards:
+```sparql
+PREFIX cs: <http://pragma.canonical.com/codestandards#>
+
+SELECT ?standard WHERE {
+  ?standard a cs:CodeStandard .
+  FILTER(STRSTARTS(STR(?standard), STR(cs:react.component.props)))
+}
+```
+
+### 7. Validate Before Committing
+
+After writing the standard, validate the Turtle syntax:
+
+```bash
+sem check code-standards
+```
+
+Then verify the standard loads correctly:
+```
+sem_lookup(type: "cs:CodeStandard", filters: {"@id": "cs:category.domain.topic"})
+```
+
+The `@id` must always use the canonical compact IRI. Do not look up standards by `cs:name`.
+
+## File Organization
+
+Standards are organized by category in `data/`:
+
+```
+code-standards/
+├── definitions/
+│   └── CodeStandard.ttl    # Ontology schema
+├── data/
+│   ├── react.ttl           # React standards
+│   ├── css.ttl             # CSS standards
+│   ├── styling.ttl         # Styling standards
+│   ├── code.ttl            # General code standards
+│   ├── storybook.ttl       # Storybook standards
+│   └── icons.ttl           # Icon standards
+└── skills/
+    └── standards-guide/
+        └── SKILL.md
+```
+
+Add new standards to the file matching their category.
+
+## Writing Quality Standards
+
+### Description Guidelines
+- Start with WHAT the standard covers
+- Explain WHY it matters
+- Keep it concise but complete
+- Use markdown for complex descriptions
+
+### Do Examples Guidelines
+- Each `cs:do` blank node is one discrete positive example
+- `cs:description` explains what the example demonstrates
+- `cs:language` must match the code block language (e.g. `"typescript"`, `"css"`, `"rust"`)
+- `cs:code` contains the actual code — no markdown fences needed
+- Provide concrete, runnable examples
+- Show the COMPLETE correct pattern
+
+### Don't Examples Guidelines
+- Each `cs:dont` blank node is one discrete negative example
+- Show realistic mistakes developers make
+- `cs:description` should explain WHY it's problematic
+- Mirror the structure of the do examples where possible
+
+### Example Quality Checklist
+- [ ] Examples are syntactically correct
+- [ ] Examples are self-contained (can be understood without context)
+- [ ] Examples use realistic code, not `foo`/`bar`
+- [ ] Examples include comments explaining key points
+- [ ] Both do's and don'ts cover the same scenarios
+
+## Complete Example
+
+Adding a new standard for React error boundaries:
+
+```turtle
+# In data/react.ttl
+
+cs:react.component.error_boundaries a cs:CodeStandard ;
+    cs:name "React Error Boundaries" ;
+    cs:hasCategory cs:react ;
+    cs:description "Error boundaries must be used to catch JavaScript errors in component trees and display fallback UI. They should be placed strategically to isolate failures without breaking the entire application." ;
+    cs:do [
+        cs:description "Wrap feature sections with error boundaries to isolate failures." ;
+        cs:language "tsx" ;
+        cs:code """
+const Dashboard = () => (
+  <div className="ds dashboard">
+    <ErrorBoundary fallback={<WidgetError />}>
+      <AnalyticsWidget />
+    </ErrorBoundary>
+    <ErrorBoundary fallback={<WidgetError />}>
+      <ActivityWidget />
+    </ErrorBoundary>
+  </div>
+);
+    """
+    ] ;
+    cs:do [
+        cs:description "Provide meaningful fallback UI that helps users understand and recover." ;
+        cs:language "tsx" ;
+        cs:code """
+const WidgetError = () => (
+  <div className="ds widget-error">
+    <p>This section couldn't load.</p>
+    <button onClick={() => window.location.reload()}>
+      Refresh page
+    </button>
+  </div>
+);
+    """
+    ] ;
+    cs:dont [
+        cs:description "Wrap the entire application in a single error boundary." ;
+        cs:language "tsx" ;
+        cs:code """
+// Bad: One error anywhere crashes everything
+const App = () => (
+  <ErrorBoundary>
+    <Header />
+    <Main />
+    <Footer />
+  </ErrorBoundary>
+);
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use generic or unhelpful fallback messages." ;
+        cs:language "tsx" ;
+        cs:code """
+// Bad: Doesn't help the user
+const fallback = <div>Something went wrong</div>;
+    """
+    ] .
+```
+
+## Tips
+
+1. **Check before creating**: Always search for existing standards first - you might need to extend rather than create new
+2. **Follow patterns**: Look at existing standards in the same category for style guidance
+3. **Be specific**: Vague standards are hard to follow - include concrete examples
+4. **Test your examples**: Make sure code examples actually work
+5. **Consider hierarchy**: Use `cs:extends` when your standard builds on another