Releave/v0.8.0

.claude/skills/_ctx-release-notes/SKILL.md

@@ -27,7 +27,9 @@ Generate release notes for the next release of Context CLI.
 1. **Read version and find baseline**:
 ```bash
 cat VERSION
-git describe --tags --abbrev=0 2>/dev/null
+# Use the latest tag globally, not ancestry-based git describe
+# (git describe follows reachability and misses tags on other branches)
+git tag --sort=-v:refname | head -1
 ```
 
 2. **Gather commits since last tag** (filter out noise):

.claude/skills/_ctx-release/SKILL.md

@@ -13,8 +13,8 @@ All three prerequisites must be true:
 2. **`dist/RELEASE_NOTES.md`** exists (generate with `/_ctx-release-notes`)
 3. **Working tree is clean** (all changes committed)
 
-If any prerequisite fails, stop — running the release script with
-missing notes or a dirty tree can produce an incomplete or unsigned
+If any prerequisite fails, stop. Running the release script with
+missing notes or a dirty tree produces an incomplete or unsigned
 tag that must be manually deleted.
 
 ## When to Use
@@ -42,17 +42,23 @@ make release
 ```
 
 This script:
-- Updates version references in `docs/index.md`
+- Updates version in 4 config files (plugin.json, marketplace.json, VS Code package.json + lock)
+- Updates download URLs in 3 doc files (index.md, getting-started.md, integrations.md)
+- Adds new row to versions.md
 - Rebuilds the documentation site
-- Commits the docs update
+- Commits the version and docs update
 - Runs tests and smoke tests
-- Builds binaries for all platforms
+- Builds binaries for all 6 platforms
 - Creates and pushes a signed git tag
 - Updates the `latest` tag
 
-3. **After completion**, tell the user to create the GitHub release
-   at the URL shown in the script output and upload binaries from
-   `dist/`.
+3. **After completion**, verify the GitHub release was created by CI
+   at `https://github.com/ActiveMemory/ctx/releases`.
+
+## Full Runbook
+
+See [Cutting a Release](https://ctx.ist/operations/release/) for the
+complete step-by-step guide including troubleshooting.
 
 ## Quality Checklist
 
@@ -61,4 +67,4 @@ This script:
 - [ ] Working tree is clean
 - [ ] Tests and smoke tests pass
 - [ ] Tag is pushed to origin
-- [ ] User reminded to create GitHub release
+- [ ] GitHub release created by CI with all 6 binaries

.context/DECISIONS.md

@@ -3,6 +3,7 @@
 <!-- INDEX:START -->
 | Date | Decision |
 |------|--------|
+| 2026-03-23 | Pre/pre HTML tags promoted to shared constants in config/marker |
 | 2026-03-23 | Pure-data param structs in entity — replace function pointers with text keys |
 | 2026-03-22 | No runtime pluralization — use singular/plural text key pairs |
 | 2026-03-22 | Output functions belong in write/, never in core/ or cmd/ |
@@ -62,6 +63,20 @@
 | 2026-02-27 | Webhook and notification design (consolidated) |
 <!-- INDEX:END -->
 
+## [2026-03-23-165612] Pre/pre HTML tags promoted to shared constants in config/marker
+
+**Status**: Accepted
+
+**Context**: Two packages (normalize and format) used hardcoded pre strings independently
+
+**Decision**: Pre/pre HTML tags promoted to shared constants in config/marker
+
+**Rationale**: Cross-package magic strings belong in config constants per CONVENTIONS.md
+
+**Consequence**: marker.TagPre and marker.TagPreClose are the canonical references; package-local constants deleted
+
+---
+
 ## [2026-03-23-003346] Pure-data param structs in entity — replace function pointers with text keys
 
 **Status**: Accepted

.context/LEARNINGS.md

@@ -3,6 +3,8 @@
 <!-- INDEX:START -->
 | Date | Learning |
 |------|--------|
+| 2026-03-23 | Typography detection script needs exclusion lists for intentional uses |
+| 2026-03-23 | Subagents rename functions and restructure code beyond their scope |
 | 2026-03-23 | Splitting core/ into subpackages reveals hidden structure |
 | 2026-03-23 | Higher-order callbacks in param structs are a code smell |
 | 2026-03-22 | Types in god-object files create circular dependencies |
@@ -91,6 +93,26 @@
 
 ---
 
+## [2026-03-23-165611] Typography detection script needs exclusion lists for intentional uses
+
+**Context**: detect-ai-typography.sh flagged config/token/delim.go (intentional delimiter constants) and test files (test data containing em-dashes)
+
+**Lesson**: Detection scripts for convention enforcement need exclusion patterns for files where the flagged patterns are intentional data, not prose
+
+**Application**: Add exclusion patterns proactively when creating detection scripts; *_test.go and constant-definition files are common false positive sources
+
+---
+
+## [2026-03-23-165610] Subagents rename functions and restructure code beyond their scope
+
+**Context**: Agents tasked with fixing em-dashes in comments also renamed exported functions, changed import aliases, and modified function signatures
+
+**Lesson**: Always diff-audit agent output for structural changes before accepting edits, even when the task is narrowly scoped
+
+**Application**: After any agent batch edit, run git diff --stat and scan for non-comment changes before staging
+
+---
+
 ## [2026-03-23-003544] Splitting core/ into subpackages reveals hidden structure
 
 **Context**: init core/ was a flat bag of domain objects — splitting into backup/, claude/, entry/, merge/, plan/, plugin/, project/, prompt/, tpl/, validate/ exposed duplicated logic, misplaced types, and function-pointer smuggling that were invisible in the flat layout

.context/TASKS.md

@@ -41,6 +41,8 @@ checks field presence, not content safety.
 
 - [ ] Make TitleSlugMaxLen configurable via .ctxrc #added:2026-03-21-070944
 
+- [ ] Replace hack/lint-drift.sh with AST-based Go tests in internal/audit/. Spec: `specs/ast-audit-tests.md` #added:2026-03-23-210000
+
 - [ ] Add AST-based lint test to detect exported functions with no external callers #added:2026-03-21-070357
 
 - [ ] Audit exported functions used only within their own package and make them private #added:2026-03-21-070346

CONTRIBUTING-SKILLS.md

@@ -6,7 +6,7 @@ session. This page is for contributors who want to understand what each
 skill does without reading individual `SKILL.md` files.
 
 For ctx plugin skills (`/ctx-status`, `/ctx-recall`, etc.), see the
-[ctx skills documentation](docs/skills.md).
+[ctx skills documentation](docs/reference/skills.md).
 
 ## Skill Catalog
 

CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 Thank you for your interest in contributing to `ctx`.
 
-**Full contributing guide**: https://ctx.ist/contributing/
+**Full contributing guide**: https://ctx.ist/home/contributing/
 
 The guide covers:
 

docs/cli/tools.md

@@ -821,7 +821,7 @@ ctx prompt rm <name>
 
 - `name`: Template name (without `.md` extension)
 
-**See also**: [Prompt Templates](../recipes/prompts.md)
+**See also**: [Prompt Templates](../recipes/prompt-templates.md)
 
 ---
 

docs/home/about.md

@@ -135,7 +135,7 @@ makes the *next* session **smarter**.
 **Connect with `ctx`**
 
 * [Join the Community →](community.md): ask questions, share workflows, and help shape what comes next
-* [Read the Blog →](../../blog/): real-world patterns, ponderings, and lessons learned from building `ctx` using `ctx`
+* [Read the Blog →](../blog/): real-world patterns, ponderings, and lessons learned from building `ctx` using `ctx`
 
 ----
 

docs/home/contributing.md

@@ -120,7 +120,7 @@ ctx/
 
 | Directory                        | What lives here                                 | Distributed to users? |
 |----------------------------------|-------------------------------------------------|-----------------------|
-| `internal/assets/claude/skills/` | The 29 `ctx-*` skills that ship with the plugin | Yes                   |
+| `internal/assets/claude/skills/` | The 39 `ctx-*` skills that ship with the plugin | Yes                   |
 | `.claude/skills/`                | Dev-only skills (release, QA, backup, etc.)     | No                    |
 
 **`internal/assets/claude/skills/`** is the single source of truth for
@@ -164,7 +164,7 @@ and are now available to all ctx users: `/ctx-brainstorm`, `/ctx-check-links`,
 6. Add a section to the appropriate CLI doc page in `docs/cli/`.
 
 Pattern to follow: `internal/cli/pad/pad.go` (parent with subcommands) or
-`internal/cli/complete/complete.go` (single command).
+`internal/cli/drift/drift.go` (single command).
 
 ### Adding a New Session Parser
 

docs/operations/index.md

@@ -31,6 +31,13 @@ Windsurf, and other AI coding tools.
 
 ---
 
+### [Cutting a Release](release.md)
+
+Step-by-step runbook for maintainers: bump version, generate
+release notes, run the release script, and verify the result.
+
+---
+
 ### [Autonomous Loops](autonomous-loop.md)
 
 Run an unattended AI agent that works through tasks overnight,

docs/operations/release.md

@@ -0,0 +1,178 @@
+---
+#   /    ctx:                         https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+title: Cutting a Release
+icon: lucide/package
+---
+
+![ctx](../images/ctx-banner.png)
+
+## Prerequisites
+
+Before you can cut a release you need:
+
+* Push access to `origin` (GitHub)
+* GPG signing configured (`make gpg-test`)
+* [Go](https://go.dev/) installed (version in `go.mod`)
+* [Zensical](https://github.com/zensical/zensical) installed (`make site-setup`)
+* A clean working tree (`git status` shows nothing to commit)
+
+---
+
+## Step-by-Step
+
+### 1. Update the VERSION File
+
+```bash
+echo "0.9.0" > VERSION
+git add VERSION
+git commit -m "chore: bump version to 0.9.0"
+```
+
+The VERSION file uses bare semver (`0.9.0`), no `v` prefix.
+The release script adds the `v` prefix for git tags.
+
+### 2. Generate Release Notes
+
+In Claude Code:
+
+```
+/_ctx-release-notes
+```
+
+This analyzes commits since the last tag and writes
+`dist/RELEASE_NOTES.md`. The release script refuses to
+proceed without this file.
+
+### 3. Commit Any Remaining Changes
+
+```bash
+git status          # must be clean
+make audit          # full check: fmt, vet, lint, test
+```
+
+### 4. Run the Release
+
+```bash
+make release
+```
+
+Or, if you are in a Claude Code session:
+
+```
+/_ctx-release
+```
+
+The release script does everything in order:
+
+| Step | What happens |
+|------|-------------|
+| 1 | Reads `VERSION`, verifies release notes exist |
+| 2 | Verifies working tree is clean |
+| 3 | Updates version in 4 config files (plugin.json, marketplace.json, VS Code package.json + lock) |
+| 4 | Updates download URLs in 3 doc files (index.md, getting-started.md, integrations.md) |
+| 5 | Adds new row to versions.md |
+| 6 | Rebuilds the documentation site (`make site`) |
+| 7 | Commits all version and docs updates |
+| 8 | Runs `make test` and `make smoke` |
+| 9 | Builds binaries for all 6 platforms via `hack/build-all.sh` |
+| 10 | Creates a signed git tag (`v0.9.0`) |
+| 11 | Pushes the tag to origin |
+| 12 | Updates and pushes the `latest` tag |
+
+### 5. GitHub CI Takes Over
+
+Pushing a `v*` tag triggers `.github/workflows/release.yml`:
+
+1. Checks out the tagged commit
+2. Runs the full test suite
+3. Builds binaries for all platforms
+4. Creates a GitHub Release with auto-generated notes
+5. Uploads binaries and SHA256 checksums
+
+### 6. Verify
+
+- [ ] [GitHub Releases](https://github.com/ActiveMemory/ctx/releases) shows the new version
+- [ ] All 6 binaries are attached (linux/darwin x amd64/arm64, windows x amd64)
+- [ ] SHA256 files are attached
+- [ ] Release notes look correct
+
+---
+
+## What Gets Updated Automatically
+
+The release script updates 8 files so you do not have to:
+
+| File | What changes |
+|------|-------------|
+| `internal/assets/claude/.claude-plugin/plugin.json` | Plugin version |
+| `.claude-plugin/marketplace.json` | Marketplace version (2 fields) |
+| `editors/vscode/package.json` | VS Code extension version |
+| `editors/vscode/package-lock.json` | VS Code lock version (2 fields) |
+| `docs/index.md` | Download URLs |
+| `docs/home/getting-started.md` | Download URLs |
+| `docs/operations/integrations.md` | VSIX filename version |
+| `docs/reference/versions.md` | New version row + latest pointer |
+
+The Go binary version is injected at build time via `-ldflags`
+from the VERSION file. No source file needs editing.
+
+---
+
+## Build Targets Reference
+
+| Target | What it does |
+|--------|-------------|
+| `make release` | Full release (script + tag + push) |
+| `make build` | Build binary for current platform |
+| `make build-all` | Build all 6 platform binaries |
+| `make test` | Unit tests |
+| `make smoke` | Integration smoke tests |
+| `make audit` | Full check (fmt + vet + lint + drift + docs + test) |
+| `make site` | Rebuild documentation site |
+
+---
+
+## Troubleshooting
+
+### "Release notes not found"
+
+```
+ERROR: dist/RELEASE_NOTES.md not found.
+```
+
+Run `/_ctx-release-notes` in Claude Code first, or write
+`dist/RELEASE_NOTES.md` manually.
+
+### "Working tree is not clean"
+
+```
+ERROR: Working tree is not clean.
+```
+
+Commit or stash all changes before running `make release`.
+
+### "Tag already exists"
+
+```
+ERROR: Tag v0.9.0 already exists.
+```
+
+You cannot release the same version twice. Either bump VERSION
+to a new version, or delete the old tag if the release was
+incomplete:
+
+```bash
+git tag -d v0.9.0
+git push origin :refs/tags/v0.9.0
+```
+
+### CI build fails after tag push
+
+The tag is already published. Fix the issue, bump to a patch
+version (e.g. `0.9.1`), and release again. Do not force-push
+tags that others may have already fetched.