@canonical/pragma-cli 0.35.0 → 0.37.0

package/README.md

@@ -147,7 +147,7 @@ pragma setup
 pragma doctor
 ```
 
-`pragma setup` is one wizard for the whole environment: MCP registration, shell completions, agent skills, and the LSP extension. Each installer can target your project's configuration, your user-level (global) configuration, 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`.
+`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`.
 
 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):
 
@@ -162,7 +162,7 @@ The LSP step installs the Terrazzo extension, and the extension's own log is the
 
 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.
 
-`pragma doctor` checks the environment (Node version, store health, registrations) and says what to fix. `pragma info` shows the version, the configuration in effect, and update status; `pragma upgrade` updates the CLI itself.
+`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.
 
 ## Point it at your own design system
 

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

package/bundled-skills/adoption-a1-styles/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: adoption-a1-styles
+description: Adopt Canonical design-system styles, fonts, and icons in an application (adoption track A1); also runs as a guided tutorial on a worked example
+---
+
+# Adoption A1 — Styles, fonts, icons
+
+The first track of adopting the design system: the visual foundation — reset,
+typography, tokens, fonts, icons — before any component swap. Complete this track and
+the app looks and reads like the design system even while it still renders its old
+components.
+
+## When to Use
+
+- Starting design-system adoption in an application — this is the first track
+- The app needs the visual foundation (reset, typography, tokens, fonts, icons) before
+  any component swap
+
+## When NOT to Use
+
+- The foundation is already installed and verified — continue with
+  `adoption-a2-components`
+- Authoring design-system content rather than adopting it — see `specify-component`
+  and its sibling skills
+
+## Opening move: ask, or offer the tutorial
+
+Activation is an opening, not a starting gun. Unless the first message already names
+the work, ask for the starting point — as a suggestion carrying an example, not as a
+form to fill in:
+
+> To get started, point me at the app — the repo or directory — and say whether it
+> already pulls in any Canonical styles.
+
+"I don't know what's in there" is a fine answer: the install and verify steps
+establish it. Ask again only for what the next step genuinely blocks on.
+
+If the activation message already carries the starting point, do not re-ask — say what
+you took it to be, and go.
+
+Offer the tutorial in the same breath, because this track doubles as one:
+
+> Or if you'd rather see what this track changes before touching your app, I can run
+> it as a tutorial: I'll take a plausible example — a small Vite React app — and walk
+> you through the track on it.
+
+Tutorial mode is the step narration below, turned up: the same outcome-path-conclusion
+frame, with the reasoning behind each change made explicit. It runs on a scratch
+example, not on the person's app — nothing in their repo changes unless they ask.
+
+## Every step is narrated: outcome, path, conclusion
+
+Every step is addressed to the person — once before it runs, once when it ends. This is
+not tutorial manner. It holds in the ordinary flow too: the person is the design
+authority, and they can only steer a step they saw coming. A decision gate met cold is
+a decision they cannot really make.
+
+**Open** the step with what it is FOR — the outcome it should leave behind — and how
+you are about to get there. **Close** it with a sentence saying what it established and
+what that means for the step after. One sentence each is enough; the failure mode is
+silence, not length, and a step whose outcome looks obvious still gets its sentence
+rather than a shrug.
+
+Do:
+
+> **Fonts, then styles.** The outcome is an app whose type and tokens come from the
+> design system, with the fonts loaded before the styles that expect them. The path is
+> the two `@import` lines below, in the root stylesheet, fonts first.
+>
+> …
+>
+> So: type and tokens are live and Ubuntu Sans is self-hosted — which leaves the
+> surface classes as the step that decides whether the density channel emits real
+> values at all.
+
+Don't:
+
+> Added the two imports. Fonts load.
+
+Both carry the same facts. Only the first says what the step was trying to achieve and
+what it settled — and only the first lets the person cut in with the thing they know
+and the graph does not, which is the whole reason they are here.
+
+## Asked about the skill: methodology and outcomes first
+
+A question about what this skill does — what it covers, what its steps are, how it
+works — is answered in that order: the METHOD it applies and the OUTCOMES it leaves
+the person holding come first, the step-by-step breakdown comes after.
+
+Two or three sentences of method is enough: what the skill treats as its object, the
+discipline that makes it work, and what exists at the end that did not exist before.
+The enumeration then reads as steps in service of something, rather than as a list to
+be got through.
+
+What this prevents is a table of contents standing in for an answer. A reply opening
+with the step names tells someone who already knows the skill nothing new, and someone
+who does not, nothing at all.
+
+So, asked what this skill is:
+
+> It installs the visual foundation — reset, typography, tokens, fonts, icons — before
+> any component is swapped, under the live code standards. Complete it and the app
+> looks and reads like the design system while it still renders its old components,
+> which is what makes every later track land on the right ground.
+
+Then, and only then, the breakdown.
+
+## Install
+
+```bash
+bun add @canonical/styles @canonical/ds-assets
+```
+
+One import of `@canonical/styles` aggregates the normalize/reset, typography, and design
+tokens. Two things come with it:
+
+- Cascade layers `@layer normalize, ds.reset, ds.modifiers, ds.components` — component
+  styles beat modifiers beat reset regardless of import order, so adopting apps do not
+  fight specificity.
+- `color-scheme: light dark` on `:root` — the foundation is theme-aware out of the box.
+
+## Code standards are the gate
+
+Styling work in this track falls under the live code standards — the `styling`, `css`,
+and `icons` categories at minimum (take the actual set from the live output, not from
+this list). Pull them BEFORE touching a stylesheet and hold the Do/Don't pairs open
+while editing, so they shape the change as it is written, not only in review:
+
+```bash
+pragma standard categories                 # the live category set — never from memory
+pragma standard list --category styling    # repeat per applicable category
+pragma standard lookup <name> --detail detailed
+```
+
+Apps follow the code standards as closely as the work allows. Where a change has to
+deviate from a pulled standard, record the deviation in the PR next to the standard's
+name — and ideally file it as an issue, either to bring the app into line later or to
+propose a change to the standard itself. The standards apply even when the app has no
+pragma dependency, and they are open to contribution: a missing or wrong standard is
+something to propose a change for, not to silently work around.
+
+## Fonts before styles
+
+Fonts are opt-in and must be imported FIRST. The canonical form, in the root stylesheet:
+
+```css
+@import url("@canonical/styles/fonts");
+@import url("@canonical/styles");
+```
+
+(Equivalent JS-side: import the fonts CSS, then `import "@canonical/styles"`.) The
+fonts entry loads Ubuntu Sans as variable fonts, self-hosted from
+`@canonical/ds-assets` via its `@font-face` rules — no external font host.
+
+## Declare the surface: context and density classes
+
+The density system is class-driven, and it starts at the root. The app's root element
+(`<body>`, or the app's root container) must carry TWO classes:
+
+```html
+<body class="app comfortable">
+```
+
+- **Context** — `app`, `site`, or `docs`: which surface this is. Applications take
+  `app`; marketing/brochure surfaces take `site`; documentation surfaces take `docs`
+  (`docs` shares `site`'s values).
+- **Density** — `comfortable` or `dense`: picks within the context's pair.
+  `comfortable` is the default choice unless the product's design calls for `dense`.
+
+The requirement, stated as a rule: the root carries EXACTLY ONE class from each
+family — a context (`app` | `site` | `docs`) AND a density (`comfortable` | `dense`).
+That makes six valid combinations (`app comfortable`, `app dense`, `site comfortable`,
+`site dense`, `docs comfortable`, `docs dense`) and nothing else: a single class, a
+value outside either set, or two values from the same family is an invalid surface
+declaration. `app comfortable` is the default for applications; adoption is not done
+until the root carries a valid pair.
+
+Components never read these classes directly — they read the `--density-*` custom
+properties the classes emit (control heights, inline padding, vertical spacing rungs,
+baseline seating). A section can locally tighten by carrying its own `dense` class on
+an ancestor of just that region.
+
+**Failure mode: missing root classes fail SILENTLY.** The primitives fall back to
+app-comfortable values, so an application looks right by accident — while a site or
+docs surface, or any intended `dense` region, quietly renders with the wrong control
+heights and spacing. This step has historically been forgotten precisely because
+nothing errors. If control heights or spacing look subtly off, check the root classes
+before debugging component CSS.
+
+## The /icons serving contract (and its silent failure)
+
+Icons are per-file SVGs in `@canonical/ds-assets` (`icons/<name>.svg`, 16x16 viewBox,
+`currentColor` fill, a single `<g id="<name>">`), referenced at RUNTIME: the React
+`Icon` component renders
+
+```html
+<use href="/icons/<name>.svg#<name>" />
+```
+
+with `rootPath="/icons"` as the default, overridable via the `rootPath` prop.
+
+**The app must expose `@canonical/ds-assets`' `icons/` directory at `/icons`** — copy or
+symlink it into the static dir, or add a static mount in the server/bundler config — or
+pass `rootPath` to point where the app does serve them.
+
+**Failure mode: an unserved icon renders EMPTY, silently.** No error, no broken-image
+glyph — an external `<use>` reference that 404s resolves to nothing. If icons "don't
+show up", check the network tab for `/icons/<name>.svg` before debugging anything else.
+
+For TypeScript apps, the valid icon names ship as data:
+
+```ts
+import { ICON_NAMES, type IconName } from "@canonical/ds-assets";
+```
+
+## Storybook freebies
+
+```bash
+bun add -d @canonical/storybook-config
+```
+
+```ts
+// .storybook/main.ts
+import { createConfig } from "@canonical/storybook-config";
+
+export default createConfig("react"); // or "svelte" | "sveltekit" | "lit"
+```
+
+This single call:
+
+- serves the whole `@canonical/ds-assets` package via `staticDirs`, so `/icons/*` just
+  works in Storybook — do not mistake that for your APP serving them;
+- ships the shared addons and shell theme;
+- fixes the full-height preview chain.
+
+One caveat: declare `tags: ["autodocs"]` inline in your own `.storybook/preview.ts` —
+Storybook statically parses that file and does not reliably pick up tags spread from an
+imported preview.
+
+## Verify
+
+- [ ] Computed `font-family` on body text shows Ubuntu Sans.
+- [ ] The root element carries one context class (`app`/`site`/`docs`) and one
+      density class (`comfortable`/`dense`).
+- [ ] Computed `--density-line-height` on a control matches the intended cell
+      (e.g. `32px` for app-comfortable, `36px` for site-comfortable) — a fallback
+      value on a class-less root passes visual inspection and still fails this check
+      on non-app surfaces.
+- [ ] `/icons/<name>.svg` returns 200 with SVG content, and an icon visibly renders.
+- [ ] The `@layer normalize, ds.reset, ds.modifiers, ds.components` rule is present in
+      the served CSS.
+- [ ] Typography baseline behaves. Note: the baseline grid is computed with the CSS
+      `mod()` function and cannot be downleveled — check the support table in the
+      `@canonical/styles-typography` README against the browsers you target.
+
+## Next
+
+Foundation in place — continue with `adoption-a2-components`.
+
+## Support
+
+If this skill leads somewhere broken — a command that errors, guidance that
+contradicts what the live system answers, a gap the flow cannot cover — you are not
+stuck:
+
+- Raise an issue in the pragma repo: https://github.com/canonical/pragma/issues —
+  include the skill name, what was run, and expected vs. actual outcome.
+- Or contact the design-system team owners directly through your organization's
+  professional messaging channels for assistance.