@erclx/canon 4.112.0 → 4.113.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.112.0",
+  "version": "4.113.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-feedback/SKILL.md

@@ -5,7 +5,7 @@ description: Format a report about something broken, missing, or off in canon an
 
 # Canon feedback
 
-Format a `## Toolkit feedback` block from the current session, then open it as a GitHub issue labeled `feedback` on the toolkit repo. `canon-feedback-triage` reads that queue.
+Format a `## Toolkit feedback` block from the current session, then open it as a GitHub issue on the toolkit repo, labeled `feedback` plus the domain label its surface type names. `canon-feedback-triage` reads that queue.
 
 ## Guards
 
@@ -18,7 +18,7 @@ Format a `## Toolkit feedback` block from the current session, then open it as a
 From the conversation so far, identify:
 
 - Target project name or kind, never its full path. The path names a folder on one machine and says nothing a triage session can route on, where the project's own name does. Name a private project by its kind instead, such as `a Next.js app`, since the report leaves the machine.
-- Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI)
+- Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI). The type leads the `### Surface` field, ahead of the first comma, because the CLI picks the issue's domain labels from that text alone.
 - Specific toolkit file or name when the session cites one
 - Observed behavior
 - Expected behavior, or `unclear`
@@ -81,7 +81,7 @@ cat <<'EOF' | canon feedback --github
 EOF
 ```
 
-The CLI opens a GitHub issue labeled `feedback` on the toolkit repo and prints the issue URL, which this skill reports back on its own line. It needs `gh` authenticated. `git-issue` is not the route, since it files on the current repository and this report belongs on the toolkit's.
+The CLI opens a GitHub issue on the toolkit repo, labeled `feedback` and each domain label the surface type names, such as `skills` for a plugin skill, and prints the issue URL, which this skill reports back on its own line. It needs `gh` authenticated. `git-issue` is not the route, since it files on the current repository and this report belongs on the toolkit's.
 
 From a toolkit checkout, a call that produces no URL falls back to `.canon/feedback/feedback-<slug>-<ts>.md` and prints the reason on stderr. Say so in the same reply, naming the file and the reason, since a silent fallback leaves the report where nothing reads it. A target project has no such folder, so a failed call there prints the block in chat.
 

package/docs/agents/teach.md

@@ -198,6 +198,8 @@ No `canon teach` verb serves the workspace. `canon serve` does, taking the teach
 canon serve .canon/teach --entry 03-fde-system-design/index.html --json
 ```
 
+`canon teach list <topic>` ends its human output with this line for that workspace, with the teach folder written relative to the cwd, or absolute when it sits outside it, since `canon serve` resolves its directory against the cwd while the list verb reads the main worktree root. The JSON record carries no such field.
+
 It stays general rather than becoming `canon teach serve`, because nothing about serving a directory is specific to a learning workspace, and the same verb carries a slide render and a design preview.
 
 Read `url` off the record rather than building one from the port that was asked for. The verb walks forward past a port already in use, which is routine when a second workspace is already open, and the port it took is the one thing a composed URL gets wrong.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.112.0",
+  "version": "4.113.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -49,6 +49,8 @@
     "web:previews": "bun scripts/core/regen-web-previews.ts",
     "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",
     "web:gallery": "cd web && astro build --config gallery.config.mjs",
+    "web:card": "cd web && astro dev --config card.config.mjs",
+    "web:card:check": "PROJECT_ROOT=web bash tooling/astro/configs/scripts/check-card-exclusion.sh",
     "web:preview": "cd web && astro preview",
     "web:e2e": "cd web && playwright test"
   },

package/src/claude/skills-audit.ts

@@ -1,10 +1,6 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import {
-  type Frontmatter,
-  parseFrontmatter,
-  readField,
-} from '@/indexes/frontmatter'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -149,7 +145,7 @@ async function readSkill(
       : Promise.resolve(undefined),
   ])
 
-  const fields = readFields(body)
+  const fields = parseFrontmatter(body)
 
   return {
     rel: join(rel, folder),
@@ -162,19 +158,6 @@ async function readSkill(
   }
 }
 
-/**
- * Returns undefined rather than throwing on unparseable YAML, so one malformed
- * body reports as missing its required fields instead of ending the audit
- * before it reaches the rest of the corpus.
- */
-function readFields(body: string): Frontmatter | undefined {
-  try {
-    return parseFrontmatter(body)
-  } catch {
-    return undefined
-  }
-}
-
 /**
  * A key carrying an empty value declares nothing, so blank reads as absent
  * rather than as a name that disagrees with every folder.

package/src/commands/feedback-format.ts

@@ -89,6 +89,30 @@ export function deriveSlug(body: string): string {
   return slug || SLUG_FALLBACK
 }
 
+/**
+ * Each label must exist on the toolkit repository, because `gh issue create`
+ * refuses the whole issue on an unknown label rather than dropping it.
+ */
+const DOMAIN_LABELS: readonly { pattern: RegExp; label: string }[] = [
+  { pattern: /\bskills?\b/, label: 'skills' },
+  { pattern: /\b(?:cli)s?\b/, label: 'cli' },
+  { pattern: /\b(?:tooling|seeds?)\b/, label: 'tooling' },
+  { pattern: /\b(?:governance)s?\b/, label: 'governance' },
+  { pattern: /\bsnippets?\b/, label: 'snippets' },
+]
+
+/**
+ * Reads only the surface type, the text before the first comma, so a path or
+ * name after it never adds a label.
+ */
+export function deriveDomainLabels(body: string): string[] {
+  const type = (surfaceField(body) ?? '').split(',')[0]?.toLowerCase() ?? ''
+  const labels = DOMAIN_LABELS.filter(({ pattern }) => pattern.test(type)).map(
+    ({ label }) => label,
+  )
+  return [...new Set(labels)]
+}
+
 export function deriveTitle(body: string): string {
   const surface = surfaceField(body)
   const title = surface ? `feedback: ${surface}` : 'toolkit feedback'

package/src/commands/feedback.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import {
+  deriveDomainLabels,
   deriveSlug,
   deriveTitle,
   missingField,
@@ -107,7 +108,7 @@ export function register(program: Command): void {
         const result = await createGithubIssue({
           title: deriveTitle(body),
           body,
-          labels: ['feedback'],
+          labels: ['feedback', ...deriveDomainLabels(body)],
         })
         if (result.ok) {
           frameSuccess('canon feedback', result.url)

package/src/commands/teach.ts

@@ -1,4 +1,4 @@
-import { relative } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavOutcome, generateNav } from '@/teach/nav'
@@ -18,6 +18,7 @@ import {
   type TeachRefused,
   type Term,
   type TermOutcome,
+  teachDir,
   type WorkspaceSummary,
   writeStylesheet,
 } from '@/teach/workspace'
@@ -91,6 +92,18 @@ export function register(program: Command): void {
     .command('teach')
     .description('Manage learning workspaces in .canon/teach/')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Opening a workspace:',
+        '  canon serve .canon/teach --entry <nn>-<topic>/index.html',
+        '',
+        'canon teach list <topic> prints the exact line, with the teach folder',
+        'written from where you stand rather than as this literal.',
+        '',
+      ].join('\n'),
+    )
 
   teach
     .command('list')
@@ -118,6 +131,9 @@ export function register(program: Command): void {
         'A workspace not named NN-<topic> is still listed. It sorts last and',
         'moves no ordinal, since dropping it hides the folder needing a fix.',
         '',
+        'The human output ends with the canon serve line that opens a',
+        'workspace, a template with no topic and the exact line with one.',
+        '',
         'Examples:',
         '  canon teach list',
         '  canon teach list regular-expressions --json',
@@ -852,6 +868,22 @@ function describe(workspace: WorkspaceSummary): string {
   return `${workspace.slug}: ${workspace.lessons} lesson(s), ${workspace.records} record(s), ${workspace.reference} reference page(s), ${workspace.terms} term(s)`
 }
 
+/**
+ * `canon serve` resolves its folder against the caller's cwd, while the list
+ * verb reads the teach folder at the main worktree root, so the line carries
+ * the folder actually read. A literal `.canon/teach` serves an absent folder
+ * from a linked worktree.
+ */
+function serveLine(root: string, entry: string): string {
+  const dir = resolve(teachDir(root))
+  const fromCwd = relative(process.cwd(), dir)
+  const isOutsideCwd =
+    fromCwd === '..' || fromCwd.startsWith(`..${sep}`) || isAbsolute(fromCwd)
+  const printed = fromCwd === '' ? '.' : isOutsideCwd ? dir : fromCwd
+
+  return `canon serve ${printed} --entry ${entry}`
+}
+
 function reportList(
   outcome: ListOutcome,
   emitJson: boolean,
@@ -890,6 +922,12 @@ function reportList(
 
   logStep('Next ordinal')
   logInfo(outcome.next)
+
+  if (outcome.workspaces.length > 0) {
+    logStep('Open')
+    logInfo(serveLine(root, '<nn>-<topic>/index.html'))
+  }
+
   outro()
 
   return 0
@@ -940,6 +978,8 @@ function reportWorkspace(
     logWarn(`no ${workspace.missing.join(' and no ')}`)
   }
 
+  logStep('Open')
+  logInfo(serveLine(root, `${workspace.slug}/index.html`))
   outro()
 
   return 0

package/src/indexes/frontmatter.ts

@@ -11,12 +11,21 @@ export interface Frontmatter {
  * `raw` keeps the delimiters so an index can be rewritten with its own
  * frontmatter untouched, including comments and key order that a parse and
  * re-emit would lose.
+ *
+ * A block that will not parse reads as absent rather than throwing, so one
+ * malformed file reports through the path a caller already takes for a
+ * missing block instead of ending the caller's whole run.
  */
 export function parseFrontmatter(source: string): Frontmatter | undefined {
   const match = source.match(FRONTMATTER)
   if (!match) return undefined
 
-  const parsed = Bun.YAML.parse(match[1])
+  let parsed: unknown
+  try {
+    parsed = Bun.YAML.parse(match[1])
+  } catch {
+    return undefined
+  }
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     return undefined
   }

package/src/pr/evidence.ts

@@ -106,8 +106,10 @@ export async function groupEvidence(
   return { kind: 'read', states }
 }
 
+// The raw host serves nothing to a private repository's browser, while the
+// blob form redirects to the bytes carrying the viewer's session.
 function rawUrl(repo: string, sha: string, path: string): string {
-  return `https://raw.githubusercontent.com/${repo}/${sha}/${path}`
+  return `https://github.com/${repo}/blob/${sha}/${path}?raw=true`
 }
 
 export function evidenceMarker(head: string): string {

package/src/teach/workspace.ts

@@ -579,8 +579,8 @@ function missionText(
 
   return [
     '---',
-    `title: ${title}`,
-    `description: ${request.subject}`,
+    `title: ${yamlValue(title)}`,
+    `description: ${yamlValue(request.subject)}`,
     `date: ${date}`,
     '---',
     '',
@@ -606,8 +606,8 @@ function missionText(
 function resourcesText(title: string): string {
   return [
     '---',
-    `title: Sources for ${title}`,
-    `description: Sources read for ${title}, and leads found but not opened`,
+    `title: ${yamlValue(`Sources for ${title}`)}`,
+    `description: ${yamlValue(`Sources read for ${title}, and leads found but not opened`)}`,
     '---',
     '',
     `# Sources for ${title}`,
@@ -628,8 +628,8 @@ function resourcesText(title: string): string {
 function glossaryText(title: string): string {
   return [
     '---',
-    `title: Glossary for ${title}`,
-    `description: Terms ${title} defines, one entry each`,
+    `title: ${yamlValue(`Glossary for ${title}`)}`,
+    `description: ${yamlValue(`Terms ${title} defines, one entry each`)}`,
     '---',
     '',
     `# Glossary for ${title}`,
@@ -641,6 +641,14 @@ function glossaryText(title: string): string {
   ].join('\n')
 }
 
+/**
+ * Serializes a frontmatter value, quoting only what YAML would otherwise read
+ * as something other than the string, so a plain title stays byte-identical.
+ */
+function yamlValue(value: string): string {
+  return Bun.YAML.stringify(value)
+}
+
 /** Today as `YYYY-MM-DD`, which is the one field the mission dates. */
 function today(): string {
   return new Date().toISOString().slice(0, DATE_LENGTH)

package/tooling/base/seeds/cspell.json

@@ -16,5 +16,5 @@
     }
   ],
   "dictionaries": ["project-terms", "tech-stack"],
-  "ignorePaths": [".cspell/**", ".git/**"]
+  "ignorePaths": [".cspell/**", ".git/**", ".claude/rules/canon/**"]
 }

package/tooling/claude/seeds/.claude/hooks/silent-turn.sh

@@ -49,19 +49,18 @@ paths=$(tail -n +"$line_start" "$transcript_path" | jq -r '
 
 # Two written paths can share a basename, and a bare basename match would then
 # read one mention as covering both. Counting first is what lets a collision
-# fall back to the full path, which the ordinary case never needs.
-declare -A base_count
-while IFS= read -r path; do
+# fall back to the full path, which the ordinary case never needs. The count
+# avoids an associative array, since macOS ships bash 3.2.
+colliding=$(while IFS= read -r path; do
   [ -n "$path" ] || continue
-  base=$(basename "$path")
-  base_count["$base"]=$((${base_count["$base"]:-0} + 1))
-done <<<"$paths"
+  printf '%s\n' "${path##*/}"
+done <<<"$paths" | sort | uniq -d)
 
 unmentioned=()
 while IFS= read -r path; do
   [ -n "$path" ] || continue
-  base=$(basename "$path")
-  if [ "${base_count[$base]}" -gt 1 ]; then
+  base=${path##*/}
+  if [ -n "$colliding" ] && printf '%s\n' "$colliding" | grep -Fxq -- "$base"; then
     needle="$path"
   else
     needle="$base"

package/tooling/nextjs/configs/vitest.config.ts

@@ -5,7 +5,7 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, 'src'),
+      '@': path.resolve(import.meta.dirname, 'src'),
     },
   },
   test: {

package/tooling/python/manifest.toml

@@ -2,7 +2,7 @@
 name = "python"
 extends = "base"
 runtime = "uv"
-scaffold = "uv init --app {{name}}"
+scaffold = "uv init --package {{name}}"
 
 [scripts]
 "lint" = "uv run ruff check . && uv run ruff format --check ."

package/tooling/python/reference.md

@@ -10,14 +10,13 @@ Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coverage
 
 ## Scaffold checklist
 
-1. Scaffold with `uv init --app <name>`. This creates `pyproject.toml`, `.python-version` pinned to 3.14, `src/<name>/`, and a starter `main.py`. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
+1. Scaffold with `uv init --package <name>`. This creates `pyproject.toml` with a `uv_build` backend, `.python-version` pinned to 3.14, and `src/<name with underscores>/__init__.py` holding an annotated `def main() -> None:`, so source lands under `src/` where `mypy.ini`, `pytest.ini`, and `.coveragerc` look for it. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
 2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`. Without this the sync drops base configs but skips the dep install, since `resolve_missing_deps` short-circuits when `package.json` is absent.
 3. Install base tooling: `canon tooling sync base . --write`
 4. Install python tooling: `canon tooling sync python . --write`
 5. Install Python tooling deps: `uv add --dev ruff mypy pytest pytest-cov`. v1 of this stack does not declare these in `[dependencies.dev]` because manifest injection hardcodes `bun add -D`, which can not install Python packages. Until the injector branches on `runtime`, this step is manual.
 6. Sync the lockfile and create the venv: `uv sync`.
-7. Annotate `main()` in the scaffold-generated `main.py` with `-> None`. `uv init --app` ships an unannotated `main()` that fails strict mypy on the first run.
-8. Run `bun run lint:fix` then `bun run check`.
+7. Run `bun run lint:fix` then `bun run check`.
 
 The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest` collects at least one test on first run, so `bun run test:run` exits 0 instead of the empty-collection exit code 5. Delete or replace the smoke test with real tests.
 
@@ -27,7 +26,7 @@ The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest`
 - `mypy.ini`: strict mode, `python_version = 3.14`, `mypy_path = src`, excludes `tests/` and `docs/`.
 - `pytest.ini`: tests live under `tests/`, source under `src/`.
 - `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
-- `.python-version`: pinned to `3.14` to match `uv init --app` defaults.
+- `.python-version`: pinned to `3.14` to match `uv init` defaults.
 - `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases.
 
 ## Hybrid project shape

package/tooling/vite-react/configs/vite.config.ts

@@ -9,7 +9,7 @@ export default defineConfig({
   plugins: [react(), tailwindcss()],
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, './src'),
+      '@': path.resolve(import.meta.dirname, './src'),
     },
   },
   base: process.env.VITE_BASE_URL ?? '/',