@pasko70/pibo 1.9.2 → 1.9.3

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 (120) hide show
  1. package/README.md +183 -183
  2. package/context/codex-base-prompt.md +148 -148
  3. package/context/compute-worker.md +23 -23
  4. package/context/pibo-compaction-prompt.md +100 -100
  5. package/context/pibo-native-tooling.md +18 -18
  6. package/context/pibo-system-prompt.md +77 -77
  7. package/dist/apps/chat/agent-store.js +248 -248
  8. package/dist/apps/chat/data/project-service.js +168 -168
  9. package/dist/apps/chat/data/read-state-service.js +18 -18
  10. package/dist/apps/chat/data/session-query-service.js +25 -25
  11. package/dist/apps/chat/data/timeline-query-service.js +14 -14
  12. package/dist/apps/chat/static-assets.js +854 -854
  13. package/dist/apps/chat/workflow-persistence.js +255 -255
  14. package/dist/apps/chat-ui/assets/{dist-5GM30SQK.js → dist-5WHjqNrY.js} +1 -1
  15. package/dist/apps/chat-ui/assets/{dist-Cge8JklW.js → dist-BJBNSAIH.js} +1 -1
  16. package/dist/apps/chat-ui/assets/{dist-C-5u2QIS.js → dist-C3liNPZJ.js} +1 -1
  17. package/dist/apps/chat-ui/assets/{dist-BWbWIOcD.js → dist-CW6FHEaw.js} +1 -1
  18. package/dist/apps/chat-ui/assets/{dist-CjYtD7ZT.js → dist-CaNlj6v6.js} +1 -1
  19. package/dist/apps/chat-ui/assets/{dist-BYKMZlI0.js → dist-Cne74s6i.js} +1 -1
  20. package/dist/apps/chat-ui/assets/{dist-9lsp1UpA.js → dist-DvKZv20v.js} +1 -1
  21. package/dist/apps/chat-ui/assets/{dist-DFhhiR8M.js → dist-FYH7vzrh.js} +1 -1
  22. package/dist/apps/chat-ui/assets/{dist-Etxmpyxg.js → dist-f5KioIwL.js} +1 -1
  23. package/dist/apps/chat-ui/assets/{dist-2KdPXbMT.js → dist-hWrpj7SE.js} +1 -1
  24. package/dist/apps/chat-ui/assets/{dist-Idz5kzy8.js → dist-jAuO8_bV.js} +1 -1
  25. package/dist/apps/chat-ui/assets/{index-BqD_bm7z.js → index-Bf29pJph.js} +29 -29
  26. package/dist/apps/chat-ui/index.html +17 -17
  27. package/dist/apps/chat-ui/manifest.webmanifest +25 -25
  28. package/dist/apps/chat-ui/sw.js +47 -47
  29. package/dist/apps/chat-vscode-web/assets/index-BAMxIaI_.js +41 -0
  30. package/dist/apps/chat-vscode-web/index.html +13 -13
  31. package/dist/apps/cli-ui/cliSessionsCommand.js +23 -23
  32. package/dist/apps/context-files-ui/index.html +11 -11
  33. package/dist/cli.js +39 -39
  34. package/dist/compute/cli.js +54 -54
  35. package/dist/core/session-router.js +5 -2
  36. package/dist/cron/cli.js +15 -15
  37. package/dist/cron/store.js +49 -49
  38. package/dist/data/cli.js +23 -23
  39. package/dist/data/event-log.js +23 -23
  40. package/dist/data/message-store.js +20 -20
  41. package/dist/data/navigation-store.js +9 -9
  42. package/dist/data/observation-store.js +4 -4
  43. package/dist/data/payload-store.js +17 -17
  44. package/dist/data/schema.js +431 -431
  45. package/dist/data/session-store.js +4 -4
  46. package/dist/data/telemetry-queries.js +54 -54
  47. package/dist/data/telemetry.js +197 -197
  48. package/dist/debug/events.js +12 -12
  49. package/dist/debug/failures.js +6 -6
  50. package/dist/debug/index.js +227 -227
  51. package/dist/debug/messages.js +6 -6
  52. package/dist/debug/pty.js +124 -124
  53. package/dist/debug/session.js +29 -29
  54. package/dist/debug/tools.js +5 -5
  55. package/dist/debug/web-snapshot-browser-scripts.js +294 -294
  56. package/dist/debug/web-streaming-browser-library.js +925 -925
  57. package/dist/debug/web-streaming-browser-scripts.js +232 -232
  58. package/dist/debug/web-streaming-provider-telemetry.js +4 -4
  59. package/dist/debug/web.js +93 -93
  60. package/dist/gateway/cli.js +19 -19
  61. package/dist/mcp/config-command.js +53 -53
  62. package/dist/mcp/index.js +21 -21
  63. package/dist/mcp/registry.js +11 -11
  64. package/dist/pi-packages/cli.js +11 -11
  65. package/dist/plugins/context-files-store.js +110 -110
  66. package/dist/plugins/context-files.js +4 -4
  67. package/dist/ralph/cli.js +18 -18
  68. package/dist/ralph/templates.js +140 -140
  69. package/dist/reliability/store.js +226 -226
  70. package/dist/session-ui/sessionActivity.js +30 -0
  71. package/dist/sessions/pibo-data-store.js +16 -16
  72. package/dist/sessions/sqlite-store.js +53 -53
  73. package/dist/setup/cli.js +58 -58
  74. package/dist/signals/projector.js +26 -11
  75. package/dist/signals/registry.js +41 -0
  76. package/dist/tools/agent-browser-wrapper.js +80 -80
  77. package/dist/tools/browser-use-cdp.js +12 -12
  78. package/dist/tools/browser-use-wrapper.js +762 -762
  79. package/dist/tools/guides.js +538 -538
  80. package/dist/tools/index.js +99 -99
  81. package/dist/tools/runtime/node-worker-source.js +205 -205
  82. package/dist/tools/runtime/python-worker-source.js +177 -177
  83. package/dist/vscode/cli.js +9 -9
  84. package/dist/web-annotations/cdp.js +900 -900
  85. package/dist/web-annotations/store.js +96 -96
  86. package/docs/README.md +23 -23
  87. package/docs/ops/install-developer-host.md +112 -112
  88. package/docs/ops/install-user-host.md +96 -96
  89. package/docs/ops/upgrade-user-to-developer-host.md +69 -69
  90. package/docs/ops/vscode-extension-release.md +160 -160
  91. package/package.json +95 -95
  92. package/skills/builtin/graphify/SKILL.md +52 -52
  93. package/skills/builtin/pi-agent-harness/SKILL.md +319 -319
  94. package/skills/builtin/pi-agent-harness/agents/openai.yaml +4 -4
  95. package/skills/builtin/pibo-docker-system/SKILL.md +170 -170
  96. package/skills/builtin/pibo-spec-writing/SKILL.md +330 -330
  97. package/skills/builtin/prd/SKILL.md +143 -143
  98. package/skills/builtin/ralph-loop/SKILL.md +359 -359
  99. package/skills/builtin/ralph-prd-json/SKILL.md +123 -123
  100. package/skills/builtin/skill-creator/LICENSE.txt +201 -201
  101. package/skills/builtin/skill-creator/SKILL.md +513 -513
  102. package/skills/builtin/skill-creator/agents/analyzer.md +274 -274
  103. package/skills/builtin/skill-creator/agents/comparator.md +202 -202
  104. package/skills/builtin/skill-creator/agents/grader.md +223 -223
  105. package/skills/builtin/skill-creator/assets/eval_review.html +146 -146
  106. package/skills/builtin/skill-creator/eval-viewer/generate_review.py +471 -471
  107. package/skills/builtin/skill-creator/eval-viewer/viewer.html +1325 -1325
  108. package/skills/builtin/skill-creator/references/schemas.md +430 -430
  109. package/skills/builtin/skill-creator/scripts/aggregate_benchmark.py +401 -401
  110. package/skills/builtin/skill-creator/scripts/generate_report.py +326 -326
  111. package/skills/builtin/skill-creator/scripts/improve_description.py +247 -247
  112. package/skills/builtin/skill-creator/scripts/package_skill.py +136 -136
  113. package/skills/builtin/skill-creator/scripts/quick_validate.py +102 -102
  114. package/skills/builtin/skill-creator/scripts/run_eval.py +310 -310
  115. package/skills/builtin/skill-creator/scripts/run_loop.py +328 -328
  116. package/skills/builtin/skill-creator/scripts/utils.py +47 -47
  117. package/skills/builtin/web-annotations/SKILL.md +93 -93
  118. package/src/mcp/LICENSE.mcp-cli +21 -21
  119. package/dist/apps/chat-vscode-web/assets/index-Cst9OUkC.js +0 -41
  120. package/dist/session-ui/activeTurn.js +0 -126
package/package.json CHANGED
@@ -1,95 +1,95 @@
1
- {
2
- "name": "@pasko70/pibo",
3
- "version": "1.9.2",
4
- "type": "module",
5
- "imports": {
6
- "vscode": "./src/apps/chat-vscode/extension/src/vscode-shim.js"
7
- },
8
- "description": "Minimal TypeScript wrapper around Pi Coding Agent.",
9
- "files": [
10
- "dist",
11
- "context",
12
- "skills/builtin/**",
13
- "docs/ops/**",
14
- "README.md",
15
- "src/mcp/LICENSE.mcp-cli"
16
- ],
17
- "bin": {
18
- "pibo": "dist/bin/pibo.js",
19
- "rg": "dist/bin/rg.js"
20
- },
21
- "engines": {
22
- "node": ">=24"
23
- },
24
- "scripts": {
25
- "dev": "tsx src/bin/pibo.ts",
26
- "profile": "tsx src/bin/pibo.ts profile",
27
- "tui": "tsx src/bin/pibo.ts tui",
28
- "tui:routed": "tsx src/bin/pibo.ts tui:routed",
29
- "tui:gateway": "tsx src/bin/pibo.ts tui gateway-producer",
30
- "gateway": "tsx src/bin/pibo.ts gateway",
31
- "gateway:web": "npm run web-ui:build && tsx src/bin/pibo.ts gateway:web",
32
- "client": "tsx src/bin/pibo.ts client",
33
- "chat-ui:build": "vite build --config src/apps/chat-ui/vite.config.ts",
34
- "chat-ui:typecheck": "tsc -p src/apps/chat-ui/tsconfig.json --noEmit",
35
- "context-files-ui:build": "vite build --config src/apps/context-files-ui/vite.config.ts",
36
- "context-files-ui:typecheck": "tsc -p src/apps/context-files-ui/tsconfig.json --noEmit",
37
- "web-ui:build": "npm run chat-ui:build && npm run context-files-ui:build",
38
- "vscode:typecheck": "tsc -p src/apps/chat-vscode/extension/tsconfig.json --noEmit && tsc -p src/apps/chat-vscode/extension/webview/tsconfig.json --noEmit",
39
- "vscode:webview:build": "vite build --config src/apps/chat-vscode/extension/webview/vite.config.ts",
40
- "vscode:extension:build": "esbuild src/apps/chat-vscode/extension/src/extension.ts --bundle --platform=node --target=node24 --format=cjs --outfile=src/apps/chat-vscode/dist/extension/extension.cjs --external:vscode --sourcemap=inline",
41
- "vscode:package": "node scripts/vscode-package.mjs",
42
- "release": "node scripts/release.mjs",
43
- "release:github": "node scripts/create-github-release.mjs",
44
- "build": "tsc -p tsconfig.json && npm run web-ui:build && npm run vscode:webview:build && node scripts/ensure-bin-executable.mjs",
45
- "start": "node dist/bin/pibo.js",
46
- "test": "npm run build && node --test test/*.test.mjs test/chat-vscode/*.test.mjs",
47
- "check:product-vocab": "node scripts/legacy-product-vocabulary-gate.mjs",
48
- "validate:ink-web-derived": "node scripts/ink-cli-web-derived-parity-validate.mjs",
49
- "compute:limited-worker-smoke": "node scripts/compute-limited-worker-smoke.mjs",
50
- "typecheck": "tsc -p tsconfig.json --noEmit && npm run chat-ui:typecheck && npm run context-files-ui:typecheck && npm run vscode:typecheck",
51
- "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
52
- "prepack": "npm run build"
53
- },
54
- "dependencies": {
55
- "@earendil-works/pi-agent-core": "^0.80.6",
56
- "@earendil-works/pi-ai": "^0.80.6",
57
- "@earendil-works/pi-coding-agent": "^0.80.6",
58
- "@earendil-works/pi-tui": "^0.80.6",
59
- "@mdxeditor/editor": "^3.55.0",
60
- "@modelcontextprotocol/sdk": "^1.29.0",
61
- "@tailwindcss/vite": "^4.2.4",
62
- "@tanstack/react-query": "^5.100.7",
63
- "@tanstack/react-router": "^1.168.25",
64
- "@tanstack/react-start": "^1.167.50",
65
- "@uiw/react-json-view": "^2.0.0-alpha.41",
66
- "@vscode/ripgrep": "^1.18.0",
67
- "@xyflow/react": "12.10.2",
68
- "better-auth": "^1.6.9",
69
- "commander": "^14.0.3",
70
- "ink": "^7.0.3",
71
- "lexical": "^0.35.0",
72
- "lucide-react": "^0.545.0",
73
- "prismjs": "^1.30.0",
74
- "react": "^19.2.5",
75
- "react-dom": "^19.2.5",
76
- "react-markdown": "^10.1.0",
77
- "react-virtuoso": "^4.18.6",
78
- "remark-gfm": "^4.0.1",
79
- "tailwindcss": "^4.2.4"
80
- },
81
- "devDependencies": {
82
- "@tanstack/router-plugin": "^1.167.28",
83
- "@types/node": "^25.6.0",
84
- "@types/prismjs": "^1.26.6",
85
- "@types/react": "^19.2.14",
86
- "@types/react-dom": "^19.2.3",
87
- "@vitejs/plugin-react": "^6.0.1",
88
- "@vscode/vsce": "^3.6.0",
89
- "esbuild": "^0.27.7",
90
- "tsx": "^4.21.0",
91
- "typescript": "^6.0.3",
92
- "vite": "^8.0.10",
93
- "vite-tsconfig-paths": "^5.1.4"
94
- }
95
- }
1
+ {
2
+ "name": "@pasko70/pibo",
3
+ "version": "1.9.3",
4
+ "type": "module",
5
+ "imports": {
6
+ "vscode": "./src/apps/chat-vscode/extension/src/vscode-shim.js"
7
+ },
8
+ "description": "Minimal TypeScript wrapper around Pi Coding Agent.",
9
+ "files": [
10
+ "dist",
11
+ "context",
12
+ "skills/builtin/**",
13
+ "docs/ops/**",
14
+ "README.md",
15
+ "src/mcp/LICENSE.mcp-cli"
16
+ ],
17
+ "bin": {
18
+ "pibo": "dist/bin/pibo.js",
19
+ "rg": "dist/bin/rg.js"
20
+ },
21
+ "engines": {
22
+ "node": ">=24"
23
+ },
24
+ "scripts": {
25
+ "dev": "tsx src/bin/pibo.ts",
26
+ "profile": "tsx src/bin/pibo.ts profile",
27
+ "tui": "tsx src/bin/pibo.ts tui",
28
+ "tui:routed": "tsx src/bin/pibo.ts tui:routed",
29
+ "tui:gateway": "tsx src/bin/pibo.ts tui gateway-producer",
30
+ "gateway": "tsx src/bin/pibo.ts gateway",
31
+ "gateway:web": "npm run web-ui:build && tsx src/bin/pibo.ts gateway:web",
32
+ "client": "tsx src/bin/pibo.ts client",
33
+ "chat-ui:build": "vite build --config src/apps/chat-ui/vite.config.ts",
34
+ "chat-ui:typecheck": "tsc -p src/apps/chat-ui/tsconfig.json --noEmit",
35
+ "context-files-ui:build": "vite build --config src/apps/context-files-ui/vite.config.ts",
36
+ "context-files-ui:typecheck": "tsc -p src/apps/context-files-ui/tsconfig.json --noEmit",
37
+ "web-ui:build": "npm run chat-ui:build && npm run context-files-ui:build",
38
+ "vscode:typecheck": "tsc -p src/apps/chat-vscode/extension/tsconfig.json --noEmit && tsc -p src/apps/chat-vscode/extension/webview/tsconfig.json --noEmit",
39
+ "vscode:webview:build": "vite build --config src/apps/chat-vscode/extension/webview/vite.config.ts",
40
+ "vscode:extension:build": "esbuild src/apps/chat-vscode/extension/src/extension.ts --bundle --platform=node --target=node24 --format=cjs --outfile=src/apps/chat-vscode/dist/extension/extension.cjs --external:vscode --sourcemap=inline",
41
+ "vscode:package": "node scripts/vscode-package.mjs",
42
+ "release": "node scripts/release.mjs",
43
+ "release:github": "node scripts/create-github-release.mjs",
44
+ "build": "tsc -p tsconfig.json && npm run web-ui:build && npm run vscode:webview:build && node scripts/ensure-bin-executable.mjs",
45
+ "start": "node dist/bin/pibo.js",
46
+ "test": "npm run build && node --test test/*.test.mjs test/chat-vscode/*.test.mjs",
47
+ "check:product-vocab": "node scripts/legacy-product-vocabulary-gate.mjs",
48
+ "validate:ink-web-derived": "node scripts/ink-cli-web-derived-parity-validate.mjs",
49
+ "compute:limited-worker-smoke": "node scripts/compute-limited-worker-smoke.mjs",
50
+ "typecheck": "tsc -p tsconfig.json --noEmit && npm run chat-ui:typecheck && npm run context-files-ui:typecheck && npm run vscode:typecheck",
51
+ "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
52
+ "prepack": "npm run build"
53
+ },
54
+ "dependencies": {
55
+ "@earendil-works/pi-agent-core": "^0.80.6",
56
+ "@earendil-works/pi-ai": "^0.80.6",
57
+ "@earendil-works/pi-coding-agent": "^0.80.6",
58
+ "@earendil-works/pi-tui": "^0.80.6",
59
+ "@mdxeditor/editor": "^3.55.0",
60
+ "@modelcontextprotocol/sdk": "^1.29.0",
61
+ "@tailwindcss/vite": "^4.2.4",
62
+ "@tanstack/react-query": "^5.100.7",
63
+ "@tanstack/react-router": "^1.168.25",
64
+ "@tanstack/react-start": "^1.167.50",
65
+ "@uiw/react-json-view": "^2.0.0-alpha.41",
66
+ "@vscode/ripgrep": "^1.18.0",
67
+ "@xyflow/react": "12.10.2",
68
+ "better-auth": "^1.6.9",
69
+ "commander": "^14.0.3",
70
+ "ink": "^7.0.3",
71
+ "lexical": "^0.35.0",
72
+ "lucide-react": "^0.545.0",
73
+ "prismjs": "^1.30.0",
74
+ "react": "^19.2.5",
75
+ "react-dom": "^19.2.5",
76
+ "react-markdown": "^10.1.0",
77
+ "react-virtuoso": "^4.18.6",
78
+ "remark-gfm": "^4.0.1",
79
+ "tailwindcss": "^4.2.4"
80
+ },
81
+ "devDependencies": {
82
+ "@tanstack/router-plugin": "^1.167.28",
83
+ "@types/node": "^25.6.0",
84
+ "@types/prismjs": "^1.26.6",
85
+ "@types/react": "^19.2.14",
86
+ "@types/react-dom": "^19.2.3",
87
+ "@vitejs/plugin-react": "^6.0.1",
88
+ "@vscode/vsce": "^3.6.0",
89
+ "esbuild": "^0.27.7",
90
+ "tsx": "^4.21.0",
91
+ "typescript": "^6.0.3",
92
+ "vite": "^8.0.10",
93
+ "vite-tsconfig-paths": "^5.1.4"
94
+ }
95
+ }
@@ -1,52 +1,52 @@
1
- ---
2
- name: graphify
3
- description: Use this skill when a user asks to graph, map, or visualize a codebase/workspace with Graphify and inspect the generated graphify-out/graph.html, graphify-out/graph.json, or graphify-out/GRAPH_REPORT.md artifacts.
4
- ---
5
-
6
- # Graphify Codebase Visualization
7
-
8
- Use Graphify to turn a workspace folder into an interactive knowledge graph and report. Prefer this skill for requests like "graph this repo", "visualize this codebase", "map the workspace", or "show me the project structure as a graph".
9
-
10
- ## Prerequisites
11
-
12
- Graphify is exposed as a curated Pibo CLI tool:
13
-
14
- ```bash
15
- pibo tools show graphify
16
- pibo tools install graphify
17
- eval "$(pibo tools env graphify)"
18
- ```
19
-
20
- Inside the Pibo source repo while testing local changes, use:
21
-
22
- ```bash
23
- npm run --silent dev -- tools show graphify
24
- npm run --silent dev -- tools install graphify
25
- eval "$(npm run --silent dev -- tools env graphify)"
26
- ```
27
-
28
- The Pibo installer uses the PyPI package `graphifyy` and runs `graphify install --platform pi` after installing the CLI.
29
-
30
- ## Workflow
31
-
32
- 1. Identify the workspace path from the active Pibo Room/session context or from the user's request.
33
- 2. Confirm the path is inside the intended workspace boundary before graphing.
34
- 3. Prefer an ignored artifact directory for generated files when possible. If you generate in the repo root, check `git status --short` before and after.
35
- 4. Run Graphify on the selected folder. With `graphifyy==0.9.x`, `graphify .` writes extraction output under `graphify-out/`.
36
- 5. If you need an HTML graph and markdown report from a code-only extraction without an LLM key, run `graphify cluster-only . --no-label` after `graphify .`.
37
- 6. Read `graphify-out/GRAPH_REPORT.md` first for the summary, then open `graphify-out/graph.html` when the user wants an interactive view.
38
-
39
- ```bash
40
- cd /path/to/workspace
41
- graphify .
42
- graphify cluster-only . --no-label
43
- ls graphify-out/graph.html graphify-out/graph.json graphify-out/GRAPH_REPORT.md
44
- ```
45
-
46
- ## Operating rules
47
-
48
- - Treat `graphify-out/graph.html`, `graphify-out/graph.json`, and `graphify-out/GRAPH_REPORT.md` as derived artifacts unless the user explicitly wants them committed.
49
- - Code-only extraction can run without an LLM API key. Including docs, README files, papers, images, or semantic-labeling steps may require a configured Graphify backend/API key; if no key is available, graph a code-only subdirectory or skip semantic labels with `cluster-only . --no-label`.
50
- - For large monorepos, start with a focused subdirectory such as `src/`, a code package, or a docs folder only when the needed LLM backend is configured.
51
- - Re-run Graphify on demand after branch or workspace changes; do not assume an old graph is current.
52
- - If Graphify is unavailable, report the missing install and suggest `pibo tools install graphify` rather than hand-writing a replacement graph.
1
+ ---
2
+ name: graphify
3
+ description: Use this skill when a user asks to graph, map, or visualize a codebase/workspace with Graphify and inspect the generated graphify-out/graph.html, graphify-out/graph.json, or graphify-out/GRAPH_REPORT.md artifacts.
4
+ ---
5
+
6
+ # Graphify Codebase Visualization
7
+
8
+ Use Graphify to turn a workspace folder into an interactive knowledge graph and report. Prefer this skill for requests like "graph this repo", "visualize this codebase", "map the workspace", or "show me the project structure as a graph".
9
+
10
+ ## Prerequisites
11
+
12
+ Graphify is exposed as a curated Pibo CLI tool:
13
+
14
+ ```bash
15
+ pibo tools show graphify
16
+ pibo tools install graphify
17
+ eval "$(pibo tools env graphify)"
18
+ ```
19
+
20
+ Inside the Pibo source repo while testing local changes, use:
21
+
22
+ ```bash
23
+ npm run --silent dev -- tools show graphify
24
+ npm run --silent dev -- tools install graphify
25
+ eval "$(npm run --silent dev -- tools env graphify)"
26
+ ```
27
+
28
+ The Pibo installer uses the PyPI package `graphifyy` and runs `graphify install --platform pi` after installing the CLI.
29
+
30
+ ## Workflow
31
+
32
+ 1. Identify the workspace path from the active Pibo Room/session context or from the user's request.
33
+ 2. Confirm the path is inside the intended workspace boundary before graphing.
34
+ 3. Prefer an ignored artifact directory for generated files when possible. If you generate in the repo root, check `git status --short` before and after.
35
+ 4. Run Graphify on the selected folder. With `graphifyy==0.9.x`, `graphify .` writes extraction output under `graphify-out/`.
36
+ 5. If you need an HTML graph and markdown report from a code-only extraction without an LLM key, run `graphify cluster-only . --no-label` after `graphify .`.
37
+ 6. Read `graphify-out/GRAPH_REPORT.md` first for the summary, then open `graphify-out/graph.html` when the user wants an interactive view.
38
+
39
+ ```bash
40
+ cd /path/to/workspace
41
+ graphify .
42
+ graphify cluster-only . --no-label
43
+ ls graphify-out/graph.html graphify-out/graph.json graphify-out/GRAPH_REPORT.md
44
+ ```
45
+
46
+ ## Operating rules
47
+
48
+ - Treat `graphify-out/graph.html`, `graphify-out/graph.json`, and `graphify-out/GRAPH_REPORT.md` as derived artifacts unless the user explicitly wants them committed.
49
+ - Code-only extraction can run without an LLM API key. Including docs, README files, papers, images, or semantic-labeling steps may require a configured Graphify backend/API key; if no key is available, graph a code-only subdirectory or skip semantic labels with `cluster-only . --no-label`.
50
+ - For large monorepos, start with a focused subdirectory such as `src/`, a code package, or a docs folder only when the needed LLM backend is configured.
51
+ - Re-run Graphify on demand after branch or workspace changes; do not assume an old graph is current.
52
+ - If Graphify is unavailable, report the missing install and suggest `pibo tools install graphify` rather than hand-writing a replacement graph.