@agentskit/doc-bridge 1.0.1 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/CONTRIBUTING.md +7 -0
  3. package/README.md +81 -15
  4. package/SECURITY.md +1 -1
  5. package/action.yml +2 -2
  6. package/dist/cli/program.js +1248 -316
  7. package/dist/cli/program.js.map +1 -1
  8. package/dist/config/index.d.ts +1 -1
  9. package/dist/config/index.js +338 -13
  10. package/dist/config/index.js.map +1 -1
  11. package/dist/{index-CPUJbTbg.d.ts → index-DGI9TBLE.d.ts} +906 -11
  12. package/dist/index.d.ts +65 -11
  13. package/dist/index.js +1084 -171
  14. package/dist/index.js.map +1 -1
  15. package/docs/RELEASE.md +19 -21
  16. package/docs/getting-started.md +27 -2
  17. package/docs/landing/assets/doc-bridge-hero.webp +0 -0
  18. package/docs/landing/assets/doc-bridge-surfaces.webp +0 -0
  19. package/docs/landing/assets/doc-bridge-two-way.webp +0 -0
  20. package/docs/landing/index.html +70 -10
  21. package/docs/playbook/doc-bridge-pattern.md +2 -2
  22. package/docs/recipes/index-pipeline.md +2 -2
  23. package/docs/schemas/memory-candidate-v1.md +10 -1
  24. package/docs/spec/cli.md +1 -0
  25. package/docs/spec/config-v1.md +51 -6
  26. package/docs/spec/documentation-standard-v1.md +131 -0
  27. package/ecosystem-claims.json +187 -0
  28. package/ecosystem-upstream.json +9 -0
  29. package/ecosystem.json +231 -0
  30. package/package.json +14 -2
  31. package/scripts/check-ecosystem-upstream.mjs +50 -0
  32. package/src/cli/program.ts +43 -9
  33. package/src/config/index.ts +7 -1
  34. package/src/config/load-config.ts +4 -14
  35. package/src/config/schema.ts +91 -0
  36. package/src/conformance/documentation-standard-v1.ts +502 -0
  37. package/src/conformance/ecosystem-contract.ts +175 -0
  38. package/src/gates/run-gates.ts +33 -4
  39. package/src/index-builder/human-adapters/core.ts +12 -5
  40. package/src/index-builder/human-adapters/docusaurus.ts +29 -44
  41. package/src/index-builder/human-adapters/index.ts +15 -3
  42. package/src/index-builder/scan-corpus.ts +6 -6
  43. package/src/index.ts +17 -0
  44. package/src/lib/bounded-text.ts +25 -0
  45. package/src/lib/paths.ts +20 -2
  46. package/src/lib/static-js-literal.ts +261 -0
  47. package/src/lib/walk.ts +23 -4
  48. package/src/version.ts +1 -1
@@ -0,0 +1,187 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "manifestSchemaVersion": 2,
4
+ "products": [
5
+ {
6
+ "productId": "agentskit",
7
+ "source": {
8
+ "type": "endpoint",
9
+ "url": "https://www.agentskit.io/api/stats.json"
10
+ },
11
+ "verification": "verified",
12
+ "claims": [
13
+ {
14
+ "id": "packages",
15
+ "value": 25,
16
+ "noun": "packages",
17
+ "conservativeFloor": 25,
18
+ "evidence": {
19
+ "type": "repository-derivation",
20
+ "repo": "AgentsKit-io/agentskit",
21
+ "path": "scripts/compute-stats.mjs",
22
+ "summary": "Published non-private @agentskit/* package directories."
23
+ }
24
+ },
25
+ {
26
+ "id": "framework-bindings",
27
+ "value": 7,
28
+ "noun": "framework bindings",
29
+ "evidence": {
30
+ "type": "repository-derivation",
31
+ "repo": "AgentsKit-io/agentskit",
32
+ "path": "scripts/compute-stats.mjs",
33
+ "summary": "Published framework bindings from the supported binding list."
34
+ }
35
+ },
36
+ {
37
+ "id": "native-adapters",
38
+ "value": 25,
39
+ "noun": "native adapters",
40
+ "conservativeFloor": 25,
41
+ "evidence": {
42
+ "type": "repository-derivation",
43
+ "repo": "AgentsKit-io/agentskit",
44
+ "path": "scripts/compute-stats.mjs",
45
+ "summary": "Provider exports in the adapters package excluding composition helpers."
46
+ }
47
+ },
48
+ {
49
+ "id": "integrations",
50
+ "value": 50,
51
+ "noun": "integrations",
52
+ "conservativeFloor": 50,
53
+ "evidence": {
54
+ "type": "repository-derivation",
55
+ "repo": "AgentsKit-io/agentskit",
56
+ "path": "scripts/compute-stats.mjs",
57
+ "summary": "Service directories in the integrations catalog."
58
+ }
59
+ },
60
+ {
61
+ "id": "catalog-providers",
62
+ "value": 140,
63
+ "noun": "providers",
64
+ "conservativeFloor": 140,
65
+ "evidence": {
66
+ "type": "repository-derivation",
67
+ "repo": "AgentsKit-io/agentskit",
68
+ "path": "scripts/compute-stats.mjs",
69
+ "summary": "Providers in the committed model catalog snapshot."
70
+ }
71
+ },
72
+ {
73
+ "id": "catalog-models",
74
+ "value": 5162,
75
+ "noun": "models",
76
+ "conservativeFloor": 5000,
77
+ "evidence": {
78
+ "type": "repository-derivation",
79
+ "repo": "AgentsKit-io/agentskit",
80
+ "path": "scripts/compute-stats.mjs",
81
+ "summary": "Models in the committed provider catalog snapshot."
82
+ }
83
+ },
84
+ {
85
+ "id": "skills",
86
+ "value": 21,
87
+ "noun": "ready-made skills",
88
+ "conservativeFloor": 21,
89
+ "evidence": {
90
+ "type": "repository-derivation",
91
+ "repo": "AgentsKit-io/agentskit",
92
+ "path": "scripts/compute-stats.mjs",
93
+ "summary": "Concrete skill modules excluding registry and composition helpers."
94
+ }
95
+ },
96
+ {
97
+ "id": "memory-backends",
98
+ "value": 17,
99
+ "noun": "memory backends",
100
+ "evidence": {
101
+ "type": "repository-derivation",
102
+ "repo": "AgentsKit-io/agentskit",
103
+ "path": "scripts/compute-stats.mjs",
104
+ "summary": "Concrete memory modules excluding contracts and helpers."
105
+ }
106
+ },
107
+ {
108
+ "id": "recipes",
109
+ "value": 69,
110
+ "noun": "recipes",
111
+ "conservativeFloor": 69,
112
+ "evidence": {
113
+ "type": "repository-derivation",
114
+ "repo": "AgentsKit-io/agentskit",
115
+ "path": "scripts/compute-stats.mjs",
116
+ "summary": "Published recipe MDX pages excluding indexes and metadata."
117
+ }
118
+ },
119
+ {
120
+ "id": "core-size-kb-gzip",
121
+ "value": 10,
122
+ "noun": "KB gzipped core budget",
123
+ "evidence": {
124
+ "type": "repository-derivation",
125
+ "repo": "AgentsKit-io/agentskit",
126
+ "path": "scripts/compute-stats.mjs",
127
+ "summary": "Configured ESM gzip size budget for @agentskit/core."
128
+ }
129
+ }
130
+ ]
131
+ },
132
+ {
133
+ "productId": "registry",
134
+ "source": {
135
+ "type": "endpoint",
136
+ "url": "https://registry.agentskit.io/r/index.json"
137
+ },
138
+ "verification": "declared",
139
+ "claims": []
140
+ },
141
+ {
142
+ "productId": "agentskit-chat",
143
+ "source": {
144
+ "type": "repository",
145
+ "repo": "AgentsKit-io/agentskit-chat"
146
+ },
147
+ "verification": "declared",
148
+ "claims": []
149
+ },
150
+ {
151
+ "productId": "playbook",
152
+ "source": {
153
+ "type": "endpoint",
154
+ "url": "https://playbook.agentskit.io/api/stats.json"
155
+ },
156
+ "verification": "declared",
157
+ "claims": []
158
+ },
159
+ {
160
+ "productId": "doc-bridge",
161
+ "source": {
162
+ "type": "repository",
163
+ "repo": "AgentsKit-io/doc-bridge"
164
+ },
165
+ "verification": "declared",
166
+ "claims": []
167
+ },
168
+ {
169
+ "productId": "code-review",
170
+ "source": {
171
+ "type": "repository",
172
+ "repo": "AgentsKit-io/code-review-cli"
173
+ },
174
+ "verification": "declared",
175
+ "claims": []
176
+ },
177
+ {
178
+ "productId": "akos",
179
+ "source": {
180
+ "type": "endpoint",
181
+ "url": "https://akos.agentskit.io/api/stats.json"
182
+ },
183
+ "verification": "declared",
184
+ "claims": []
185
+ }
186
+ ]
187
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "repository": "AgentsKit-io/agentskit",
4
+ "ref": "main",
5
+ "files": {
6
+ "ecosystem.json": "96ff8e60c639116b4a79302509fc8058f9cd2f4db8094677dafb61fb1bc88b58",
7
+ "ecosystem-claims.json": "eeb37363ac1461a6725f48083d7a326f0f700c0641a7a4cece2a30a3bf05d582"
8
+ }
9
+ }
package/ecosystem.json ADDED
@@ -0,0 +1,231 @@
1
+ {
2
+ "schemaVersion": 2,
3
+ "$comment": "Canonical registry of AgentsKit ecosystem products. Stable identity lives here; numeric values live in the generated ecosystem-claims ledger. The deprecated properties array temporarily preserves v1 sibling consumers.",
4
+ "parentBrand": {
5
+ "id": "agentskit",
6
+ "name": "AgentsKit"
7
+ },
8
+ "products": [
9
+ {
10
+ "id": "agentskit",
11
+ "name": "AgentsKit",
12
+ "shortName": "AgentsKit",
13
+ "kind": "library",
14
+ "role": "foundation",
15
+ "promise": "Build agents without gluing many libraries together.",
16
+ "maturity": "beta",
17
+ "repo": "AgentsKit-io/agentskit",
18
+ "accent": "#2EA043",
19
+ "surfaces": {
20
+ "home": "https://www.agentskit.io",
21
+ "docs": "https://www.agentskit.io/docs",
22
+ "llms": "https://www.agentskit.io/llms.txt",
23
+ "stats": "https://www.agentskit.io/api/stats.json",
24
+ "documentation": "fumadocs",
25
+ "chat": "custom"
26
+ },
27
+ "navigation": {
28
+ "showInBar": true,
29
+ "order": 0,
30
+ "next": ["registry", "agentskit-chat", "playbook", "doc-bridge", "code-review", "akos"]
31
+ }
32
+ },
33
+ {
34
+ "id": "registry",
35
+ "name": "AgentsKit Registry",
36
+ "shortName": "Registry",
37
+ "kind": "registry",
38
+ "role": "starting-point",
39
+ "promise": "Copy ready-made agents and own the source.",
40
+ "maturity": "beta",
41
+ "repo": "AgentsKit-io/agentskit-registry",
42
+ "accent": "#58A6FF",
43
+ "surfaces": {
44
+ "home": "https://registry.agentskit.io",
45
+ "docs": "https://registry.agentskit.io/docs",
46
+ "llms": "https://registry.agentskit.io/llms.txt",
47
+ "stats": "https://registry.agentskit.io/r/index.json",
48
+ "documentation": "fumadocs",
49
+ "chat": "custom"
50
+ },
51
+ "navigation": {
52
+ "showInBar": true,
53
+ "order": 1,
54
+ "next": ["agentskit", "playbook", "agentskit-chat"]
55
+ }
56
+ },
57
+ {
58
+ "id": "agentskit-chat",
59
+ "name": "AgentsKit Chat",
60
+ "shortName": "Chat",
61
+ "kind": "framework",
62
+ "role": "experience",
63
+ "promise": "Define one agent experience and deliver it across interfaces.",
64
+ "maturity": "alpha",
65
+ "repo": "AgentsKit-io/agentskit-chat",
66
+ "accent": "#F59E0B",
67
+ "surfaces": {
68
+ "home": "https://github.com/AgentsKit-io/agentskit-chat",
69
+ "docs": "https://github.com/AgentsKit-io/agentskit-chat/tree/main/docs",
70
+ "documentation": "repository",
71
+ "chat": "none"
72
+ },
73
+ "navigation": {
74
+ "showInBar": true,
75
+ "order": 2,
76
+ "next": ["agentskit", "registry", "doc-bridge"]
77
+ }
78
+ },
79
+ {
80
+ "id": "playbook",
81
+ "name": "Agents Playbook",
82
+ "shortName": "Playbook",
83
+ "kind": "methodology",
84
+ "role": "discipline",
85
+ "promise": "Make agents ship code a human would actually merge.",
86
+ "maturity": "stable",
87
+ "repo": "AgentsKit-io/agents-playbook",
88
+ "accent": "#8B5CF6",
89
+ "surfaces": {
90
+ "home": "https://playbook.agentskit.io",
91
+ "docs": "https://playbook.agentskit.io/docs",
92
+ "llms": "https://playbook.agentskit.io/llms.txt",
93
+ "stats": "https://playbook.agentskit.io/api/stats.json",
94
+ "documentation": "fumadocs",
95
+ "chat": "custom"
96
+ },
97
+ "navigation": {
98
+ "showInBar": true,
99
+ "order": 3,
100
+ "next": ["doc-bridge", "code-review", "agentskit"]
101
+ }
102
+ },
103
+ {
104
+ "id": "doc-bridge",
105
+ "name": "Doc Bridge",
106
+ "shortName": "Doc Bridge",
107
+ "kind": "developer-tool",
108
+ "role": "understanding",
109
+ "promise": "Turn repository documentation into executable agent handoffs.",
110
+ "maturity": "stable",
111
+ "repo": "AgentsKit-io/doc-bridge",
112
+ "accent": "#06B6D4",
113
+ "surfaces": {
114
+ "home": "https://github.com/AgentsKit-io/doc-bridge",
115
+ "docs": "https://github.com/AgentsKit-io/doc-bridge/tree/master/docs",
116
+ "documentation": "repository",
117
+ "chat": "none"
118
+ },
119
+ "navigation": {
120
+ "showInBar": true,
121
+ "order": 4,
122
+ "next": ["playbook", "code-review", "agentskit-chat"]
123
+ }
124
+ },
125
+ {
126
+ "id": "code-review",
127
+ "name": "AgentsKit Code Review",
128
+ "shortName": "Code Review",
129
+ "kind": "developer-tool",
130
+ "role": "verification",
131
+ "promise": "Run deep, low-noise review with the model already in use.",
132
+ "maturity": "alpha",
133
+ "repo": "AgentsKit-io/code-review-cli",
134
+ "accent": "#F97316",
135
+ "surfaces": {
136
+ "home": "https://github.com/AgentsKit-io/code-review-cli",
137
+ "docs": "https://github.com/AgentsKit-io/code-review-cli#readme",
138
+ "documentation": "repository",
139
+ "chat": "none"
140
+ },
141
+ "navigation": {
142
+ "showInBar": false,
143
+ "next": ["playbook", "agentskit", "doc-bridge"]
144
+ }
145
+ },
146
+ {
147
+ "id": "akos",
148
+ "name": "AgentsKit OS",
149
+ "shortName": "AKOS",
150
+ "kind": "product",
151
+ "role": "operation",
152
+ "promise": "Run and govern agents in production.",
153
+ "maturity": "stable",
154
+ "repo": "AgentsKit-io/agentskit-os",
155
+ "accent": "#34D399",
156
+ "surfaces": {
157
+ "home": "https://akos.agentskit.io",
158
+ "docs": "https://akos.agentskit.io/docs",
159
+ "llms": "https://akos.agentskit.io/llms.txt",
160
+ "stats": "https://akos.agentskit.io/api/stats.json",
161
+ "documentation": "fumadocs",
162
+ "chat": "none"
163
+ },
164
+ "navigation": {
165
+ "showInBar": true,
166
+ "order": 5,
167
+ "next": ["agentskit", "registry", "playbook"]
168
+ }
169
+ }
170
+ ],
171
+ "properties": [
172
+ {
173
+ "id": "agentskit",
174
+ "name": "AgentsKit",
175
+ "barLabel": "AgentsKit",
176
+ "domain": "www.agentskit.io",
177
+ "url": "https://www.agentskit.io",
178
+ "repo": "AgentsKit-io/agentskit",
179
+ "tagline": "Build agents without gluing many libraries together.",
180
+ "kind": "library",
181
+ "accent": "#2EA043",
182
+ "llms": "https://www.agentskit.io/llms.txt",
183
+ "stats": "https://www.agentskit.io/api/stats.json"
184
+ },
185
+ {
186
+ "id": "akos",
187
+ "name": "AgentsKit OS",
188
+ "barLabel": "AKOS",
189
+ "domain": "akos.agentskit.io",
190
+ "url": "https://akos.agentskit.io",
191
+ "repo": "AgentsKit-io/agentskit-os",
192
+ "tagline": "Run and govern agents in production.",
193
+ "kind": "product",
194
+ "accent": "#34D399",
195
+ "llms": "https://akos.agentskit.io/llms.txt",
196
+ "stats": "https://akos.agentskit.io/api/stats.json"
197
+ },
198
+ {
199
+ "id": "playbook",
200
+ "name": "Agents Playbook",
201
+ "barLabel": "Playbook",
202
+ "domain": "playbook.agentskit.io",
203
+ "url": "https://playbook.agentskit.io",
204
+ "repo": "AgentsKit-io/agents-playbook",
205
+ "tagline": "Make agents ship code a human would actually merge.",
206
+ "kind": "methodology",
207
+ "accent": "#8B5CF6",
208
+ "llms": "https://playbook.agentskit.io/llms.txt",
209
+ "stats": "https://playbook.agentskit.io/api/stats.json"
210
+ },
211
+ {
212
+ "id": "registry",
213
+ "name": "AgentsKit Registry",
214
+ "barLabel": "Registry",
215
+ "domain": "registry.agentskit.io",
216
+ "url": "https://registry.agentskit.io",
217
+ "repo": "AgentsKit-io/agentskit-registry",
218
+ "tagline": "Copy ready-made agents and own the source.",
219
+ "kind": "registry",
220
+ "accent": "#58A6FF",
221
+ "llms": "https://registry.agentskit.io/llms.txt",
222
+ "stats": "https://registry.agentskit.io/r/index.json"
223
+ }
224
+ ],
225
+ "builder": {
226
+ "id": "emersonbraun",
227
+ "name": "Emerson Braun",
228
+ "url": "https://emersonbraun.dev",
229
+ "$comment": "Link-source only. The builder is not a peer product and is not shown in shared product navigation."
230
+ }
231
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentskit/doc-bridge",
3
- "version": "1.0.1",
3
+ "version": "1.1.1",
4
4
  "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -23,6 +23,10 @@
23
23
  "bin",
24
24
  "action.yml",
25
25
  "scripts/prepare.mjs",
26
+ "scripts/check-ecosystem-upstream.mjs",
27
+ "ecosystem.json",
28
+ "ecosystem-claims.json",
29
+ "ecosystem-upstream.json",
26
30
  "docs",
27
31
  "examples",
28
32
  "README.md",
@@ -36,10 +40,12 @@
36
40
  "src"
37
41
  ],
38
42
  "scripts": {
43
+ "prebuild": "node scripts/sync-version.mjs",
39
44
  "build": "tsup",
40
45
  "test": "vitest run",
41
46
  "test:watch": "vitest",
42
47
  "coverage": "vitest run --coverage",
48
+ "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
43
49
  "typecheck": "tsc --noEmit",
44
50
  "smoke:packaged": "node scripts/smoke-packaged.mjs",
45
51
  "smoke:docsites": "node scripts/smoke-docsites.mjs",
@@ -48,7 +54,8 @@
48
54
  "coverage:badge": "node scripts/update-coverage-badge.mjs",
49
55
  "changeset": "changeset",
50
56
  "version-packages": "changeset version",
51
- "release": "pnpm build && pnpm test && changeset publish",
57
+ "release": "npm run build && npm test && changeset publish",
58
+ "version": "node scripts/sync-version.mjs && git add package.json src/version.ts",
52
59
  "prepublishOnly": "npm run build && npm test",
53
60
  "prepare": "node scripts/prepare.mjs",
54
61
  "prepack": "npm run build"
@@ -113,6 +120,11 @@
113
120
  "typescript": "^6.0.3",
114
121
  "vitest": "^4.1.9"
115
122
  },
123
+ "pnpm": {
124
+ "overrides": {
125
+ "esbuild": "^0.28.1"
126
+ }
127
+ },
116
128
  "directories": {
117
129
  "doc": "docs",
118
130
  "example": "examples",
@@ -0,0 +1,50 @@
1
+ #!/usr/bin/env node
2
+ import { createHash } from 'node:crypto'
3
+ import { readFileSync } from 'node:fs'
4
+ import { dirname, join, resolve } from 'node:path'
5
+ import { fileURLToPath } from 'node:url'
6
+
7
+ const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
8
+ const metadata = JSON.parse(readFileSync(join(root, 'ecosystem-upstream.json'), 'utf8'))
9
+ if (metadata.schemaVersion !== 1 || typeof metadata.repository !== 'string' || typeof metadata.ref !== 'string') {
10
+ throw new Error('Invalid ecosystem-upstream.json metadata.')
11
+ }
12
+
13
+ const sha256 = (value) => createHash('sha256').update(value).digest('hex')
14
+ const requiredFiles = ['ecosystem.json', 'ecosystem-claims.json']
15
+ if (
16
+ !metadata.files ||
17
+ Object.keys(metadata.files).length !== requiredFiles.length ||
18
+ requiredFiles.some((file) => !/^[a-f0-9]{64}$/.test(metadata.files[file] ?? ''))
19
+ ) {
20
+ throw new Error('Upstream metadata must contain SHA-256 digests for both canonical files.')
21
+ }
22
+
23
+ const fetchText = async (url) => {
24
+ let lastError
25
+ for (let attempt = 1; attempt <= 2; attempt += 1) {
26
+ try {
27
+ const response = await fetch(url, { signal: AbortSignal.timeout(10_000) })
28
+ if (!response.ok) throw new Error(`HTTP ${response.status}`)
29
+ return await response.text()
30
+ } catch (error) {
31
+ lastError = error
32
+ }
33
+ }
34
+ throw new Error(`Unable to verify ${url}: ${lastError instanceof Error ? lastError.message : String(lastError)}`)
35
+ }
36
+
37
+ for (const file of requiredFiles) {
38
+ const expectedDigest = metadata.files[file]
39
+ const local = readFileSync(join(root, file), 'utf8')
40
+ const localDigest = sha256(local)
41
+ if (localDigest !== expectedDigest) {
42
+ throw new Error(`${file} differs from its recorded upstream SHA-256 digest.`)
43
+ }
44
+ const url = `https://raw.githubusercontent.com/${metadata.repository}/${metadata.ref}/${file}`
45
+ const upstream = await fetchText(url)
46
+ if (sha256(upstream) !== expectedDigest || upstream !== local) {
47
+ throw new Error(`${file} is stale against ${metadata.repository}@${metadata.ref}. Sync the canonical snapshot and digest.`)
48
+ }
49
+ process.stdout.write(`ecosystem upstream parity: ${file}\n`)
50
+ }
@@ -4,6 +4,11 @@ import { createInterface } from 'node:readline/promises'
4
4
 
5
5
  import { loadConfig, projectRootFromConfigPath } from '../config/load-config.js'
6
6
  import type { DocBridgeConfigV1 } from '../config/schema.js'
7
+ import {
8
+ DOCUMENTATION_STANDARD_V1_ID,
9
+ formatDocumentationStandardText,
10
+ runDocumentationStandardV1,
11
+ } from '../conformance/documentation-standard-v1.js'
7
12
  import { buildDocBridgeIndex } from '../index-builder/build-index.js'
8
13
  import { discoverPnpmPackages } from '../index-builder/plugins/pnpm-monorepo.js'
9
14
  import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
@@ -55,6 +60,7 @@ type Command =
55
60
  | 'chat'
56
61
  | 'rag'
57
62
  | 'list'
63
+ | 'conformance'
58
64
 
59
65
  const usage = `ak-docs — human↔agent documentation bridge (@agentskit/doc-bridge)
60
66
 
@@ -63,11 +69,12 @@ Core (no API key):
63
69
  ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
64
70
  ak-docs doctor [--text] [--badge] [--write-badge]
65
71
  ak-docs index [--watch]
66
- ak-docs query <package|ownership|intent|change> <id> [--agent] [--text]
72
+ ak-docs query [package|ownership|intent|change] <id> [--agent] [--text]
67
73
  ak-docs search <term> [--agent] [--text]
68
74
  ak-docs list <packages|intents|changes|knowledge> [--text]
69
75
  ak-docs ask [question] local consult (no LLM)
70
76
  ak-docs gate run [gate-id]
77
+ ak-docs conformance run documentation-standard-v1 [--text|--json]
71
78
  ak-docs mcp
72
79
  ak-docs mcp install --cursor | --claude
73
80
  ak-docs memory ingest|classify|promote [--pr] [--dry-run]
@@ -92,7 +99,13 @@ Global flags:
92
99
 
93
100
  const QUERY_KINDS = new Set<QueryKind>(['package', 'ownership', 'intent', 'change', 'search'])
94
101
  const LIST_KINDS = new Set(['packages', 'intents', 'changes', 'knowledge'])
95
- const GATE_IDS = new Set<GateId>(['index-freshness', 'human-guide-links', 'okf-type', 'docs-style'])
102
+ const GATE_IDS = new Set<GateId>([
103
+ 'index-freshness',
104
+ 'human-guide-links',
105
+ 'okf-type',
106
+ 'docs-style',
107
+ 'documentation-standard-v1',
108
+ ])
96
109
 
97
110
  const parseArgs = (argv: readonly string[]) => {
98
111
  const flags = new Set<string>()
@@ -136,6 +149,7 @@ const parseArgs = (argv: readonly string[]) => {
136
149
  else if (positional[0] === 'chat') command = 'chat'
137
150
  else if (positional[0] === 'rag') command = 'rag'
138
151
  else if (positional[0] === 'list') command = 'list'
152
+ else if (positional[0] === 'conformance') command = 'conformance'
139
153
 
140
154
  return { command, flags, configPath, positional }
141
155
  }
@@ -782,12 +796,12 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
782
796
  const action = positional[1]
783
797
  const gateId = positional[2] as GateId | undefined
784
798
  if (action !== 'run') {
785
- process.stderr.write('Usage: ak-docs gate run [index-freshness]\n')
799
+ process.stderr.write('Usage: ak-docs gate run [gate-id]\n')
786
800
  return 1
787
801
  }
788
802
  if (gateId && !GATE_IDS.has(gateId)) {
789
803
  process.stderr.write(
790
- `Unsupported gate "${gateId}". Supported gates: index-freshness, human-guide-links, okf-type, docs-style\n`,
804
+ `Unsupported gate "${gateId}". Supported gates: ${[...GATE_IDS].join(', ')}\n`,
791
805
  )
792
806
  return 1
793
807
  }
@@ -802,6 +816,25 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
802
816
  }
803
817
  }
804
818
 
819
+ if (command === 'conformance') {
820
+ const action = positional[1]
821
+ const profile = positional[2]
822
+ if (action !== 'run' || profile !== DOCUMENTATION_STANDARD_V1_ID) {
823
+ process.stderr.write(`Usage: ak-docs conformance run ${DOCUMENTATION_STANDARD_V1_ID} [--text|--json]\n`)
824
+ return 1
825
+ }
826
+ try {
827
+ const { config, root } = loadProject(configPath)
828
+ const report = runDocumentationStandardV1(root, config)
829
+ if (wantsTextOutput(flags, config)) writeLines(formatDocumentationStandardText(report))
830
+ else writeJson(report)
831
+ return report.ok ? 0 : 1
832
+ } catch (error) {
833
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
834
+ return 1
835
+ }
836
+ }
837
+
805
838
  if (command === 'mcp') {
806
839
  if (positional[1] === 'install') {
807
840
  const target = flags.has('--claude') ? 'claude' : flags.has('--cursor') ? 'cursor' : undefined
@@ -901,14 +934,15 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
901
934
  }
902
935
 
903
936
  if (command === 'query') {
904
- const kind = positional[1] as QueryKind | undefined
905
- const id = positional[2]
906
- if (!kind || !QUERY_KINDS.has(kind) || kind === 'search') {
907
- process.stderr.write('Usage: ak-docs query <package|ownership|intent|change> <id> [--agent]\n')
937
+ const maybeKind = positional[1] as QueryKind | undefined
938
+ if (maybeKind === 'search') {
939
+ process.stderr.write('Usage: ak-docs query [package|ownership|intent|change] <id> [--agent]\n')
908
940
  return 1
909
941
  }
942
+ const kind = maybeKind && QUERY_KINDS.has(maybeKind) ? maybeKind : 'package'
943
+ const id = kind === maybeKind ? positional[2] : positional[1]
910
944
  if (!id) {
911
- process.stderr.write(`Missing id for query kind "${kind}".\n`)
945
+ process.stderr.write('Usage: ak-docs query [package|ownership|intent|change] <id> [--agent]\n')
912
946
  return 1
913
947
  }
914
948
  try {
@@ -10,6 +10,12 @@ export {
10
10
  DocBridgeConfigV1Schema,
11
11
  AgentCorpusConfigSchema,
12
12
  HumanCorpusConfigSchema,
13
+ DocumentationStandardRuleIdSchema,
14
+ DocumentationStandardV1ConfigSchema,
15
+ EcosystemContractEvidenceSchema,
16
+ ConformanceConfigSchema,
13
17
  type DocBridgeConfigV1,
14
18
  type AgentCorpusConfig,
15
- } from './schema.js'
19
+ type DocumentationStandardRuleId,
20
+ type DocumentationStandardV1Config,
21
+ } from './schema.js'