workspacejson · qmarcelle · Jul 31, 2026 · Jul 31, 2026
diff --git a/PLAN.md b/PLAN.md
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -52,7 +52,7 @@ export default defineConfig({
 			},
 			social: [
 				{ icon: 'rss', label: 'RSS', href: '/blog/rss.xml' },
-				{ icon: 'github', label: 'GitHub', href: `https://github.com/${contract.tools.audit.publicationRepository}` },
+				{ icon: 'github', label: 'GitHub', href: `https://github.com/${contract.site.repository}` },
 			],
 			customCss: ['./src/styles/custom.css'],
 			expressiveCode: {
@@ -144,7 +144,7 @@ export default defineConfig({
 				}),
 				starlightTags(),
 				starlightGiscus({
-					repo: 'workspace-json/agents-workspace',
+					repo: 'workspacejson/workspacejson.dev',
 					repoId: 'R_kgDOSUthVw',
 					category: 'Announcements',
 					categoryId: 'DIC_kwDOSUthV84C8gzk',

diff --git a/src/content/docs/audit.mdx b/src/content/docs/audit.mdx
@@ -23,11 +23,20 @@ head:
         "installUrl": "https://www.npmjs.com/package/agents-audit",
         "codeRepository": "https://github.com/workspacejson/cli",
         "license": "https://github.com/workspacejson/cli/blob/main/LICENSE",
-        "author": { "@type": "Organization", "name": "Vreko", "url": "https://vreko.dev" },
+        "author": { "@type": "Organization", "name": "Marcelle Labs" },
         "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }
       }
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="note" title="Frozen at {{PKG_VERSION}}">
+`agents-audit` is the frozen audit and compatibility surface. No new features
+will be added. For workspace.json generation and ongoing CLI development, use
+[`@workspacejson/cli`](https://www.npmjs.com/package/@workspacejson/cli) instead.
+See the [changelog](/changelog/) for details.
+</Aside>
+
 ## 1. Quick Start
 
 Run the audit tool against any repository:

diff --git a/src/content/docs/blog/local-daemon-vs-cloud.mdx b/src/content/docs/blog/local-daemon-vs-cloud.mdx
@@ -72,8 +72,7 @@ head:
         "inLanguage": "en",
         "author": {
           "@type": "Organization",
-          "name": "Vreko",
-          "url": "https://vreko.dev"
+          "name": "Marcelle Labs"
         },
         "publisher": {
           "@id": "https://workspacejson.dev/#organization"

diff --git a/src/content/docs/blog/workspace-json-vs-agents-md.md b/src/content/docs/blog/workspace-json-vs-agents-md.md
@@ -40,9 +40,9 @@ AI coding agents need context to work well. Two formats have emerged to provide
 
 ## The core distinction
 
-`AGENTS.md` is **descriptive and instructional**. It's a markdown file you write in natural language telling the agent how to behave: "run tests with `pnpm test`", "never modify files in `vendor/`", "use conventional commits".
+`AGENTS.md` is **prescriptive and instructional**. It's a markdown file you write in natural language telling the agent how to behave: "run tests with `pnpm test`", "never modify files in `vendor/`", "use conventional commits".
 
-`workspace.json` is **prescriptive and structural**. It's a machine-readable JSON file that encodes what's true about your repository: which packages exist, what files they own, what frameworks they use, how active they are.
+`workspace.json` is **descriptive and structural**. It's a machine-readable JSON file that encodes what's true about your repository: which packages exist, what files they own, what frameworks they use, how active they are.
 
 One is a memo. The other is a manifest.
 

diff --git a/src/content/docs/ecosystem.mdx b/src/content/docs/ecosystem.mdx
@@ -52,17 +52,30 @@ workspace.json and MCP operate at different points in the agent lifecycle:
   than a committed file can track.
 
 The two are complementary. An MCP server can *read* workspace.json to seed
-its context (Vreko does this in its MCP server). An agent receiving MCP
-context can use workspace.json for the structural and historical signals that
-MCP doesn't model natively.
+its context ([`@workspacejson/codex-mcp`](/implementations/codex/) does this).
+An agent receiving MCP context can use workspace.json for the structural and
+historical signals that MCP doesn't model natively.
 
 An MCP server that reads and exposes workspace.json is a reference integration
 pattern — see the [Implementations](/implementations/) page for tools that
 implement this.
 
 workspace.json does not depend on MCP and works without it.
 
-## AI Coding Agent Integrations
+## Shipped Consumer Integrations
+
+The following tools currently read workspace.json in production:
+
+- **[Codex](/implementations/codex/)** — MCP server, deterministic pre-edit hook, and read-only GPT-5.6 reviewer for OpenAI Codex.
+- **[Buildomator](https://buildomator.com)** (formerly gsd-plugin) — Claude Code consumer that reads `.agents/workspace.json` at SessionStart.
+
+See the [Implementations](/implementations/) page for the full list.
+
+## Hypothetical Compatibility
+
+The following tools do **not** currently read workspace.json, but their
+architecture is compatible with it. These are opportunities for tool authors,
+not claims of existing support.
 
 ### workspace.json and Claude Code
 
@@ -100,8 +113,7 @@ agent instruction convention that workspace.json is designed to complement.
 Goose's toolbox model (extensions that provide context and actions) maps
 naturally onto workspace.json: an extension could read workspace.json to
 surface fragility warnings, surface co-change patterns before edits, or
-report workspace health state. This integration is not built yet and is
-listed in the [Implementations](/implementations/) page as an opportunity.
+report workspace health state. This integration is not built yet.
 
 ### workspace.json and Cline
 
@@ -128,18 +140,6 @@ context in workspace.json. The `generated` section — fragility scores, co-chan
 patterns, framework manifest — provides the kind of repository intelligence that
 helps Copilot agents reason about impact and risk.
 
-## workspace.json and Goose (Extended)
-
-[Goose](https://block.github.io/goose/) is Block's open-source AI developer
-agent. Goose reads AGENTS.md when present and is a primary consumer of the
-agent instruction convention that workspace.json is designed to complement.
-
-Goose's toolbox model (extensions that provide context and actions) maps
-naturally onto workspace.json: an extension could read workspace.json to
-surface fragility warnings before edits, expose co-change patterns as Goose
-context, or report workspace health state. This integration is listed in the
-[Implementations](/implementations/) page as an opportunity for tool authors.
-
 ## The Broader Picture
 
 workspace.json is currently maintained by Marcelle Labs under a single-steward

diff --git a/src/content/docs/faq.mdx b/src/content/docs/faq.mdx
@@ -67,7 +67,7 @@ head:
             "name": "How often should workspace.json be regenerated?",
             "acceptedAnswer": {
               "@type": "Answer",
-              "text": "As often as your generator supports. Vreko regenerates continuously through daemon-based behavioral observation. Other generators may run on commit, on a schedule, or on demand. Daily or per-PR regeneration is a reasonable starting point. The file is designed to be committed, so regeneration frequency determines the granularity of your commit history."
+              "text": "As often as your generator supports. @workspacejson/cli generates on demand from git history. Daemon-based generators like Vreko regenerate continuously. Other generators may run on commit, on a schedule, or on demand. Daily or per-PR regeneration is a reasonable starting point. The file is designed to be committed, so regeneration frequency determines the granularity of your commit history."
             }
           },
           {
@@ -91,7 +91,7 @@ head:
             "name": "How does workspace.json get populated?",
             "acceptedAnswer": {
               "@type": "Answer",
-              "text": "Two tiers: Static analysis (agents-audit CLI) runs npx agents-audit scan . to generate workspace.json from git history, approximating aiModificationCount and humanModificationCount from commit metadata. It runs once on demand with no background process. Live behavioral observation (daemon) observes file system events in real time and attributes modifications to the tool that triggered them. Counts become empirical as sessions accumulate. The daemon writes only to repos where workspace.json has been explicitly initialized. Both tiers produce spec-compliant workspace.json files. The static tier is immediately useful. The live tier produces higher-fidelity signals over time."
+              "text": "Two tiers: Static analysis (@workspacejson/cli or agents-audit) generates workspace.json from git history, deriving fragility scores and co-change patterns from commit metadata. It runs once on demand with no background process. Live behavioral observation (daemon) observes file system events in real time and attributes modifications to the tool that triggered them. Signals become empirical as sessions accumulate. The daemon writes only to repos where workspace.json has been explicitly initialized. Both tiers produce spec-compliant workspace.json files. The static tier is immediately useful. The live tier produces higher-fidelity signals over time."
             }
           },
           {
@@ -115,7 +115,7 @@ head:
             "name": "Do I need to install Vreko to use workspace.json?",
             "acceptedAnswer": {
               "@type": "Answer",
-              "text": "No. workspace.json is an open specification. You can write a minimal workspace.json by hand, generate it with any tool that implements the spec, or use agents-audit to validate one. Vreko is the reference implementation — it provides daemon-based behavioral observation to generate richer workspace.json files — but the spec is tool-agnostic and open."
+              "text": "No. workspace.json is an open specification. You can write a minimal workspace.json by hand, generate it with @workspacejson/cli or any tool that implements the spec, or use agents-audit to validate one. Vreko is a daemon-based generator that produces richer workspace.json files through continuous behavioral observation, but the spec is tool-agnostic and open."
             }
           },
           {
@@ -239,26 +239,27 @@ of MUST NOT fields.
 
 ## How often should workspace.json be regenerated?
 
-As often as your generator supports. Vreko regenerates continuously as it observes
-the codebase; other generators might run on commit, on a schedule, or on demand.
-Daily or per-PR regeneration is a reasonable starting point for teams that don't
-have a daemon-based generator.
+As often as your generator supports. `@workspacejson/cli` generates on demand
+from git history. Daemon-based generators like Vreko regenerate continuously as
+they observe the codebase. Other generators might run on commit, on a schedule,
+or on demand. Daily or per-PR regeneration is a reasonable starting point for
+teams that don't have a daemon-based generator.
 
 ## How does workspace.json get populated?
 
 Two tiers of tooling produce workspace.json files. Both produce spec-compliant
 output; they differ in how they observe the codebase and the fidelity of the
 signals they produce.
 
-**Static analysis (`agents-audit` CLI)**
+**Static analysis (`@workspacejson/cli` or `agents-audit`)**
 
-Run `npx agents-audit scan .` to generate a workspace.json from git history.
-`aiModificationCount` and `humanModificationCount` are approximated from commit
-metadata and tool signatures. The scan runs once on explicit invocation — there
-are no hooks, no background process, no daemon.
+Run `npx @workspacejson/cli generate .` to generate a workspace.json from git history.
+Fragility scores and co-change patterns are derived from commit metadata. The scan
+runs once on explicit invocation — there are no hooks, no background process, no
+daemon.
 
 ```bash
-npx agents-audit scan .
+npx @workspacejson/cli generate .
 ```
 
 This is useful immediately, before any daemon is running, and produces valid
@@ -273,9 +274,8 @@ accumulate. The daemon writes only to repositories where workspace.json has been
 explicitly initialized.
 
 This is how [Vreko](https://vreko.dev) operates. The live tier produces
-higher-fidelity `aiModificationCount` and `humanModificationCount` signals over
-time because it attributes changes at the session level rather than inferring
-them from commit metadata.
+higher-fidelity fragility and co-change signals over time because it attributes
+changes at the session level rather than inferring them from commit metadata.
 
 Both tiers produce spec-compliant workspace.json files. The static tier is
 immediately useful with no ongoing process. The live tier produces richer signals
@@ -316,19 +316,21 @@ the root file.
 ## Do I need to install Vreko to use workspace.json?
 
 No. workspace.json is an open specification. You can write a minimal
-`workspace.json` by hand, generate it with any tool that implements the
-spec, or use `agents-audit` to validate one.
+`workspace.json` by hand, generate it with `@workspacejson/cli` or any tool
+that implements the spec, or use `agents-audit` to validate one.
 
-[Vreko](https://vreko.dev) is the reference implementation — it provides
-daemon-based behavioral observation to generate richer workspace.json files — but
-the spec is tool-agnostic and open.
+[Vreko](https://vreko.dev) is a daemon-based generator that produces richer
+workspace.json files through continuous behavioral observation — but the spec
+is tool-agnostic and open.
 
 ## What tools currently support workspace.json?
 
-The reference CLI [agents-audit](/audit/) reads workspace.json when present.
-[Vreko](https://vreko.dev) generates workspace.json as part of its daemon output.
-Other implementations are early; see the [Implementations](/implementations/) page
-for the current list.
+The neutral CLI [`@workspacejson/cli`](https://www.npmjs.com/package/@workspacejson/cli)
+generates and validates workspace.json. [`agents-audit`](/audit/) reads workspace.json
+when present. [Vreko](https://vreko.dev) generates workspace.json as part of its daemon
+output. Shipped consumers include [Codex](/implementations/codex/) and
+[Buildomator](https://buildomator.com). See the [Implementations](/implementations/)
+page for the full list.
 
 ## How is the spec governed?
 
@@ -362,10 +364,10 @@ ambiguous current state.
 
 ## Does workspace.json support AI attribution for code changes?
 
-v{{SPEC_VERSION}} does not include a dedicated AI attribution field. The `aiModificationCount`
-and `humanModificationCount` fields in `fileIndex` are aggregate counts — they
-record how many times a file was modified by AI-assisted versus human-driven
-sessions, without identifying which session or contributor.
+v{{SPEC_VERSION}} does not include a dedicated AI attribution field. The `fragility`
+section records per-file change counts, revert counts, and fragility scores —
+aggregate signals about how files change, without identifying which session or
+contributor.
 
 AI attribution as a structured field is under consideration for a future version.
 For teams tracking AI contributions now, the combination of workspace.json commit

diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Getting Started"
-description: "How to add workspace.json to your repository, run your first audit with agents-audit, and validate your workspace.json file in CI. Quick start guide for workspace.json."
+description: "How to add workspace.json to your repository with @workspacejson/cli, validate with agents-audit, and set up CI. Quick start guide for workspace.json."
 tableOfContents: true
 sidebar:
   order: 0
@@ -14,25 +14,25 @@ head:
         "@context": "https://schema.org",
         "@type": "HowTo",
         "name": "Getting Started with workspace.json",
-        "description": "How to add workspace.json to your repository and validate it with agents-audit.",
+        "description": "How to add workspace.json to your repository with @workspacejson/cli and validate it with agents-audit.",
         "url": "https://workspacejson.dev/getting-started/",
         "step": [
           {
             "@type": "HowToStep",
             "position": 1,
-            "name": "Install agents-audit",
-            "text": "Run npx agents-audit from your repository root — no installation required."
+            "name": "Generate workspace.json",
+            "text": "Run npx @workspacejson/cli generate . from your repository root."
           },
           {
             "@type": "HowToStep",
             "position": 2,
-            "name": "Run your first audit",
-            "text": "cd your-repo && npx agents-audit"
+            "name": "Audit with agents-audit",
+            "text": "Run npx agents-audit to check AGENTS.md hygiene and workspace.json consistency."
           },
           {
             "@type": "HowToStep",
             "position": 3,
-            "name": "Create a minimal workspace.json",
+            "name": "Understand the minimal workspace.json structure",
             "text": "Create .agents/workspace.json with specVersion 0.4 and the four required top-level sections: manual, generated, agents, health."
           },
           {
@@ -52,50 +52,35 @@ intelligence. A machine-generated JSON file committed to your repository — it
 gives AI coding agents structured facts about your codebase without requiring
 them to read every file.
 
-**TL;DR**: Run `npx agents-audit scan .` in your repository right now. You'll get a
-hygiene score for your `AGENTS.md` and, if present, your `workspace.json`.
+**TL;DR**: Run `npx @workspacejson/cli generate .` in your repository to generate
+a workspace.json, then `npx agents-audit` to check hygiene.
 
 ## What You'll Have After This Guide
 
-- A passing `npx agents-audit` run in your repo
+- A generated `workspace.json` committed to git
 - Understanding of the workspace.json format
+- A passing `npx agents-audit` run in your repo
 - CI validation set up with GitHub Actions
-- A minimal `workspace.json` committed to git
 
 ---
 
-## 1. Install agents-audit
-
-No installation required — run directly with npx:
-
-```bash
-npx agents-audit
-```
+## 1. Generate workspace.json
 
-Or install globally:
-
-```bash
-npm install -g agents-audit
-```
-
-agents-audit runs in any repository. It doesn't require workspace.json to be
-present — it will audit your `AGENTS.md` and tell you what's missing.
-
-<Aside type="note">
-The `agents-audit` package is frozen at {{PKG_VERSION}}. For ongoing
-development, use the neutral CLI `@workspacejson/cli` instead:
+The neutral CLI `@workspacejson/cli` generates workspace.json from your repository:
 
 ```bash
 npx @workspacejson/cli generate .
 ```
 
-The neutral CLI succeeds `agents-audit` with the same command surface and
-is actively developed in [workspacejson/cli](https://github.com/workspacejson/cli).
-</Aside>
+This writes `.agents/workspace.json` with the four required top-level sections
+(`manual`, `generated`, `agents`, `health`) populated from your repository.
+
+The CLI is actively developed in [workspacejson/cli](https://github.com/workspacejson/cli).
 
-## 2. Run Your First Audit
+## 2. Audit with agents-audit
 
-From your repository root:
+`agents-audit` is the frozen audit and compatibility surface at {{PKG_VERSION}}.
+It checks `AGENTS.md` hygiene and `workspace.json` consistency:
 
 ```bash
 cd your-repo
@@ -122,7 +107,17 @@ Example output:
 
 The score drops below 70 if any `error`-severity findings exist.
 
-## 3. Create a Minimal workspace.json
+<Aside type="note">
+`agents-audit` is frozen at {{PKG_VERSION}} — no new features will be added.
+For generation and ongoing development, use `@workspacejson/cli` instead.
+See the [changelog](/changelog/) for the version history.
+</Aside>
+
+## 3. Minimal workspace.json Structure
+
+If you used `npx @workspacejson/cli generate .` in step 1, you already have a
+complete `workspace.json`. This section shows the minimal valid structure for
+reference or for hand-authoring a file without a generator.
 
 The minimum valid `workspace.json` for v{{SPEC_VERSION}} requires all four sections:
 
@@ -139,7 +134,7 @@ The minimum valid `workspace.json` for v{{SPEC_VERSION}} requires all four secti
 }
 ```
 
-Create it at `.agents/workspace.json`:
+To create one manually at `.agents/workspace.json`:
 
 ```bash
 mkdir -p .agents
@@ -157,7 +152,7 @@ cat > .agents/workspace.json << 'EOF'
 EOF
 ```
 
-Commit it:
+Then commit it:
 
 ```bash
 git add .agents/workspace.json