djournal 0.10.0 → 0.12.0
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.
- package/.agents/adapters/contract.md +7 -0
- package/.grokbot/README.md +10 -0
- package/README.md +24 -7
- package/bin/journal.js +71 -49
- package/docs/architecture.md +4 -0
- package/docs/djournal-in-practice.md +2 -0
- package/docs/grok-bot.md +80 -0
- package/docs/installation.md +130 -6
- package/docs/read-only-team-journal.md +2 -1
- package/docs/recall.md +1 -0
- package/docs/remote-sync.md +1 -1
- package/docs/uninstalling.md +5 -2
- package/integrations/grok-bot/README.md +50 -0
- package/integrations/grok-bot/checkup.md +41 -0
- package/integrations/grok-bot/getting-started.md +50 -0
- package/integrations/grok-bot/peer-briefing.md +22 -0
- package/integrations/grok-bot/skill-registration.md +61 -0
- package/lib/installer/index.js +65 -1
- package/lib/setup-entries.js +108 -0
- package/lib/setup-filters.js +72 -0
- package/lib/setup-search.js +87 -0
- package/lib/setup-style.js +142 -0
- package/lib/setup.js +396 -0
- package/package.json +6 -2
|
@@ -16,6 +16,13 @@ second workflow engine and do not own durable state.
|
|
|
16
16
|
An adapter may omit events its harness cannot support reliably. Instruction-only
|
|
17
17
|
behavior remains the compatibility baseline.
|
|
18
18
|
|
|
19
|
+
Grok Bot is an instruction and skill-only harness. It has no SessionStart or
|
|
20
|
+
Stop hooks, so it omits every semantic event. Compliance is the installed
|
|
21
|
+
skills, `AGENTS.md`, and the `djournal` / `journal` CLI. The recipe lives at
|
|
22
|
+
`integrations/grok-bot/` and is described in `docs/grok-bot.md`. Adding that
|
|
23
|
+
harness does not change `AUTOMATION.md`. Hooks on other harnesses still must
|
|
24
|
+
not write semantic journal entries.
|
|
25
|
+
|
|
19
26
|
## Input
|
|
20
27
|
|
|
21
28
|
The shared checker accepts one JSON object on stdin. It uses only stable fields:
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Grok Bot marker
|
|
2
|
+
|
|
3
|
+
This directory marks a project for the djournal `grok-bot` harness.
|
|
4
|
+
|
|
5
|
+
Grok Bot has no session hooks. Journal compliance comes from the installed
|
|
6
|
+
skills, `AGENTS.md`, and `djournal` / `journal` commands. The Journal Hub
|
|
7
|
+
recipe installed with this harness lives at `integrations/grok-bot/`.
|
|
8
|
+
|
|
9
|
+
Register skills from `integrations/grok-bot/skill-registration.md`. See
|
|
10
|
+
`docs/grok-bot.md` in the djournal package for the architecture.
|
package/README.md
CHANGED
|
@@ -20,9 +20,9 @@ models, people, and tools.
|
|
|
20
20
|
|
|
21
21
|
Long coding sessions do not survive tool boundaries well when the only handoff
|
|
22
22
|
format is a transcript. A useful session may start in Codex, continue in Claude
|
|
23
|
-
Code, and later resume somewhere else. The journal is the
|
|
24
|
-
layer: each agent can read the same Markdown spine, follow the
|
|
25
|
-
and research links, and close its work in the same structure.
|
|
23
|
+
Code or Grok Bot, and later resume in Pi or somewhere else. The journal is the
|
|
24
|
+
portable handoff layer: each agent can read the same Markdown spine, follow the
|
|
25
|
+
same decisions and research links, and close its work in the same structure.
|
|
26
26
|
|
|
27
27
|
The memory belongs to the project, not to a chat session, model, harness,
|
|
28
28
|
database, or proprietary service.
|
|
@@ -113,6 +113,7 @@ flowchart LR
|
|
|
113
113
|
- Skills handle planning, research, decisions, documentation, recall, audit,
|
|
114
114
|
reconciliation, and session closure.
|
|
115
115
|
- Codex, Claude Code, and Pi integrations provide reminders and closure validation.
|
|
116
|
+
- Grok Bot uses the same skills and instructions without session hooks.
|
|
116
117
|
- Hooks never create or modify semantic journal entries.
|
|
117
118
|
- Read-only and trivial requests do not generate unnecessary ceremony.
|
|
118
119
|
|
|
@@ -162,17 +163,27 @@ Requires Node.js 18 or newer. Run this from the project you want to equip:
|
|
|
162
163
|
|
|
163
164
|
```bash
|
|
164
165
|
npm install -g djournal
|
|
165
|
-
djournal
|
|
166
|
+
djournal
|
|
166
167
|
```
|
|
167
168
|
|
|
169
|
+
Run `djournal` or `journal` without arguments to open the interactive journal.
|
|
170
|
+
Browse work, search with Recall, open entries in your editor, manage sharing,
|
|
171
|
+
and inspect project status. Installation, configuration, upgrades, diagnostics,
|
|
172
|
+
and uninstall are available from the same menu. `djournal setup` remains an
|
|
173
|
+
explicit way to open it, including `--target /path/to/project`.
|
|
174
|
+
|
|
175
|
+
Existing commands remain available for direct use and automation. The wizard
|
|
176
|
+
requires an interactive terminal; use `djournal --help` to see the commands.
|
|
177
|
+
|
|
168
178
|
The global install gives you the `djournal` and `journal` commands. The
|
|
169
|
-
installer targets the current directory and detects Codex, Claude Code,
|
|
170
|
-
explicitly when needed:
|
|
179
|
+
installer targets the current directory and detects Codex, Claude Code, Pi, or
|
|
180
|
+
a `.grokbot/` marker. Select explicitly when needed:
|
|
171
181
|
|
|
172
182
|
```bash
|
|
173
183
|
djournal install --harness codex
|
|
174
184
|
djournal install --harness claude-code
|
|
175
185
|
djournal install --harness pi
|
|
186
|
+
djournal install --harness grok-bot
|
|
176
187
|
djournal install --all
|
|
177
188
|
```
|
|
178
189
|
|
|
@@ -209,6 +220,11 @@ Pi, or use `pi --approve` for a non-interactive run. Pi has no built-in
|
|
|
209
220
|
filesystem sandbox; when an external sandbox or container is used, expose the
|
|
210
221
|
global store referenced by `.djournal.json`.
|
|
211
222
|
|
|
223
|
+
Grok Bot has no session hooks. `djournal install --harness grok-bot` installs
|
|
224
|
+
the shared skills and a Journal Hub recipe under `integrations/grok-bot/`.
|
|
225
|
+
Register those skills in Grok, then let engineering bots journal themselves.
|
|
226
|
+
See [Grok Bot](docs/grok-bot.md).
|
|
227
|
+
|
|
212
228
|
## Lifecycle
|
|
213
229
|
|
|
214
230
|
```bash
|
|
@@ -279,7 +295,7 @@ release data is refreshed in the background at most once every 24 hours. Run
|
|
|
279
295
|
|
|
280
296
|
## Status
|
|
281
297
|
|
|
282
|
-
Codex, Claude Code, and
|
|
298
|
+
Codex, Claude Code, Pi, and Grok Bot are supported. OpenCode and Zed adapters are planned. Grok Bot is instruction and skill only.
|
|
283
299
|
|
|
284
300
|
Git-backed sharing and automatic sync are opt-in so local-only work remains
|
|
285
301
|
private by default.
|
|
@@ -297,6 +313,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
|
|
|
297
313
|
## Documentation
|
|
298
314
|
|
|
299
315
|
- [Installation and repository layouts](docs/installation.md)
|
|
316
|
+
- [Grok Bot](docs/grok-bot.md)
|
|
300
317
|
- [Fast recall: CLI and agent usage](docs/recall.md)
|
|
301
318
|
- [Remote Git sync setup](docs/remote-sync.md)
|
|
302
319
|
- [Read-only team journal access](docs/read-only-team-journal.md)
|
package/bin/journal.js
CHANGED
|
@@ -25,6 +25,9 @@ const sourceRoot = path.resolve(__dirname, "..");
|
|
|
25
25
|
|
|
26
26
|
function usage() {
|
|
27
27
|
return `Usage:
|
|
28
|
+
djournal Open the interactive journal
|
|
29
|
+
journal Alias for djournal
|
|
30
|
+
journal setup [--target DIR]
|
|
28
31
|
journal install [--target DIR] [--harness LIST | --all | --instructions-only]
|
|
29
32
|
journal upgrade [--target DIR]
|
|
30
33
|
journal uninstall [--target DIR] [--harness LIST | --all]
|
|
@@ -56,7 +59,7 @@ Options:
|
|
|
56
59
|
--limit N Limit recall results per kind (1-100)
|
|
57
60
|
--rebuild Rebuild the persistent recall cache from scratch
|
|
58
61
|
--no-cache Search with an ephemeral in-memory index
|
|
59
|
-
--harness LIST Comma-separated codex,claude-code,pi
|
|
62
|
+
--harness LIST Comma-separated codex, claude-code (claude), pi, grok-bot (grok, grokbot)
|
|
60
63
|
--all Select all work items for share, or every harness
|
|
61
64
|
--instructions-only Install core instructions without harness hooks
|
|
62
65
|
`;
|
|
@@ -64,8 +67,9 @@ Options:
|
|
|
64
67
|
|
|
65
68
|
function parseArgs(argv) {
|
|
66
69
|
const args = [...argv];
|
|
67
|
-
const command = args.shift();
|
|
68
|
-
if (
|
|
70
|
+
const command = args.length ? args.shift() : "setup";
|
|
71
|
+
if (["--help", "-h"].includes(command)) throw new InstallerError(usage(), "HELP");
|
|
72
|
+
if (!["setup", "install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update", "work", "recall"].includes(command)) {
|
|
69
73
|
throw new InstallerError(usage(), "USAGE");
|
|
70
74
|
}
|
|
71
75
|
const options = { command, harnesses: [] };
|
|
@@ -89,6 +93,9 @@ function parseArgs(argv) {
|
|
|
89
93
|
}
|
|
90
94
|
while (args.length) {
|
|
91
95
|
const arg = args.shift();
|
|
96
|
+
if (command === "setup" && !["--target", "--help", "-h"].includes(arg) && !arg.startsWith("--target=")) {
|
|
97
|
+
throw new InstallerError("setup supports only --target and --help; use direct commands for automation", "USAGE");
|
|
98
|
+
}
|
|
92
99
|
if (command === "recall" && options.subcommand === "files" && arg === "--") {
|
|
93
100
|
(options.paths ||= []).push(...args.splice(0));
|
|
94
101
|
} else if (arg === "--repository") {
|
|
@@ -182,95 +189,103 @@ function parseArgs(argv) {
|
|
|
182
189
|
return options;
|
|
183
190
|
}
|
|
184
191
|
|
|
185
|
-
function print(value, json) {
|
|
192
|
+
function print(value, json, output = process.stdout) {
|
|
186
193
|
if (json) {
|
|
187
|
-
|
|
194
|
+
output.write(`${JSON.stringify(value, null, 2)}\n`);
|
|
188
195
|
return;
|
|
189
196
|
}
|
|
190
197
|
if (value.action === "update-check") {
|
|
191
|
-
|
|
192
|
-
if (value.projectVersion)
|
|
193
|
-
|
|
194
|
-
if (value.updateAvailable)
|
|
195
|
-
else if (value.latestVersion)
|
|
196
|
-
if (value.projectUpdateAvailable)
|
|
197
|
-
if (value.checkedAt)
|
|
198
|
+
output.write(`cli version: ${value.cliVersion || "unknown"}\n`);
|
|
199
|
+
if (value.projectVersion) output.write(`project assets: ${value.projectVersion}\n`);
|
|
200
|
+
output.write(`latest version: ${value.latestVersion || "unknown"}\n`);
|
|
201
|
+
if (value.updateAvailable) output.write(`update available: ${value.cliVersion} -> ${value.latestVersion}\n`);
|
|
202
|
+
else if (value.latestVersion) output.write("djournal CLI is up to date\n");
|
|
203
|
+
if (value.projectUpdateAvailable) output.write(`project upgrade available: ${value.projectVersion} -> ${value.cliVersion}\n`);
|
|
204
|
+
if (value.checkedAt) output.write(`checked: ${value.checkedAt}\n`);
|
|
198
205
|
return;
|
|
199
206
|
}
|
|
200
207
|
if (value.action === "work-list") {
|
|
201
|
-
if (value.selected)
|
|
208
|
+
if (value.selected) output.write(`selected: ${value.selected}\n`);
|
|
202
209
|
for (const item of value.workItems || []) {
|
|
203
210
|
const marker = item.selected ? "*" : " ";
|
|
204
|
-
|
|
211
|
+
output.write(`${marker} ${item.slug} [${item.status}] ${item.title}\n`);
|
|
205
212
|
}
|
|
206
213
|
return;
|
|
207
214
|
}
|
|
208
215
|
if (value.action === "work-bind") {
|
|
209
|
-
|
|
216
|
+
output.write(`bound ${value.work} to session ${value.sessionHash}\n`);
|
|
210
217
|
return;
|
|
211
218
|
}
|
|
212
219
|
if (value.action === "recall-files") {
|
|
213
|
-
|
|
220
|
+
output.write(`recall files: ${value.cache.status} (${value.cache.mode}), ${value.entries.length}/${value.totalEntries} entries\n`);
|
|
214
221
|
for (const entry of value.entries) {
|
|
215
|
-
|
|
222
|
+
output.write(`${entry.path} ${entry.title}\n`);
|
|
216
223
|
for (const match of entry.matches) {
|
|
217
224
|
const detail = match.kind === "linked_context" ? `via ${match.viaPath}` : `${match.recordedPath} (${match.scope}, ${match.evidence.provenance})`;
|
|
218
|
-
|
|
225
|
+
output.write(` ${match.inputPath}: ${match.kind} — ${detail}\n`);
|
|
219
226
|
}
|
|
220
|
-
for (const replacement of entry.supersededBy)
|
|
221
|
-
if (entry.matchesTruncated || entry.codeReferencesTruncated || entry.supersededByTruncated)
|
|
227
|
+
for (const replacement of entry.supersededBy) output.write(` superseded by: ${replacement.path}\n`);
|
|
228
|
+
if (entry.matchesTruncated || entry.codeReferencesTruncated || entry.supersededByTruncated) output.write(" additional entry evidence truncated\n");
|
|
222
229
|
}
|
|
223
|
-
if (value.unmatchedPaths.length)
|
|
224
|
-
if (value.truncated || value.relatedTruncated)
|
|
225
|
-
for (const item of value.warnings)
|
|
226
|
-
|
|
230
|
+
if (value.unmatchedPaths.length) output.write(`no indexed evidence: ${value.unmatchedPaths.join(", ")}\n`);
|
|
231
|
+
if (value.truncated || value.relatedTruncated) output.write("results or linked context truncated; narrow paths or raise --limit\n");
|
|
232
|
+
for (const item of value.warnings) output.write(`warning: ${item.code}\n`);
|
|
233
|
+
output.write("Evidence candidates only; read canonical entries before assessing the change.\n");
|
|
227
234
|
return;
|
|
228
235
|
}
|
|
229
236
|
if (value.action === "recall-index") {
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
for (const item of value.warnings || [])
|
|
237
|
+
output.write(`recall index: ${value.cache.status} (${value.cache.mode})\n`);
|
|
238
|
+
output.write(`documents: ${value.cache.documentCount}\n`);
|
|
239
|
+
output.write(`elapsed: ${value.cache.totalMs.toFixed(1)} ms\n`);
|
|
240
|
+
for (const item of value.warnings || []) output.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
|
|
234
241
|
return;
|
|
235
242
|
}
|
|
236
243
|
if (value.action === "recall-search") {
|
|
237
|
-
|
|
244
|
+
output.write(`recall search: ${value.cache.status} (${value.cache.mode}), ${value.cache.totalMs.toFixed(1)} ms\n`);
|
|
238
245
|
for (const item of [...(value.workItems || []), ...(value.entries || [])]) {
|
|
239
|
-
|
|
246
|
+
output.write(`${item.score.toFixed(2).padStart(8)} ${item.path} ${item.title}\n`);
|
|
240
247
|
}
|
|
241
|
-
for (const item of value.warnings || [])
|
|
248
|
+
for (const item of value.warnings || []) output.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
|
|
242
249
|
return;
|
|
243
250
|
}
|
|
244
|
-
if (value.action)
|
|
245
|
-
else if (typeof value.installed === "boolean")
|
|
246
|
-
else
|
|
247
|
-
if (value.harnesses)
|
|
248
|
-
if (value.key)
|
|
249
|
-
else if (value.config)
|
|
250
|
-
if (value.cliVersion)
|
|
251
|
-
if (value.projectVersion)
|
|
252
|
-
if (value.latestVersion)
|
|
253
|
-
if (value.updateAvailable)
|
|
254
|
-
if (value.projectUpdateAvailable)
|
|
251
|
+
if (value.action) output.write(`${value.action}: ${value.target}\n`);
|
|
252
|
+
else if (typeof value.installed === "boolean") output.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
|
|
253
|
+
else output.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
|
|
254
|
+
if (value.harnesses) output.write(`harnesses: ${value.harnesses.join(", ") || "instructions-only"}\n`);
|
|
255
|
+
if (value.key) output.write(`${value.key}: ${JSON.stringify(value.value)}\n`);
|
|
256
|
+
else if (value.config) output.write(`${JSON.stringify(value.config, null, 2)}\n`);
|
|
257
|
+
if (value.cliVersion) output.write(`cli version: ${value.cliVersion}\n`);
|
|
258
|
+
if (value.projectVersion) output.write(`project assets: ${value.projectVersion}\n`);
|
|
259
|
+
if (value.latestVersion) output.write(`latest version: ${value.latestVersion}\n`);
|
|
260
|
+
if (value.updateAvailable) output.write("update available: yes\n");
|
|
261
|
+
if (value.projectUpdateAvailable) output.write("project upgrade available: yes\n");
|
|
255
262
|
if (value.recallCache) {
|
|
256
263
|
const cache = value.recallCache;
|
|
257
|
-
|
|
264
|
+
output.write(`recall cache: ${cache.valid ? `${cache.documentCount} documents, ${cache.indexVersion}` : (cache.exists ? "invalid; rebuilds on next recall" : "not built")}\n`);
|
|
258
265
|
}
|
|
259
266
|
if (value.workItems) {
|
|
260
267
|
for (const item of value.workItems) {
|
|
261
|
-
|
|
262
|
-
|
|
268
|
+
if (typeof item === "string") {
|
|
269
|
+
output.write(`${item}\n`);
|
|
270
|
+
continue;
|
|
271
|
+
}
|
|
272
|
+
output.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
|
|
273
|
+
if (item.warning) output.write(`warning: ${item.warning}\n`);
|
|
263
274
|
}
|
|
264
275
|
}
|
|
265
|
-
if (value.
|
|
276
|
+
if (value.work) output.write(`work: ${value.work}\n`);
|
|
277
|
+
if (value.shared) output.write("marked for sharing\n");
|
|
278
|
+
if (value.skipped) output.write(`skipped: ${value.reason || "no changes required"}\n`);
|
|
279
|
+
if (value.warning) output.write(`warning: ${value.warning}\n`);
|
|
280
|
+
if (value.conflicts?.length) output.write(`conflicts: ${value.conflicts.join(", ")}\n`);
|
|
266
281
|
if (value.files) {
|
|
267
282
|
for (const file of value.files) {
|
|
268
|
-
if (typeof file === "string")
|
|
269
|
-
else
|
|
283
|
+
if (typeof file === "string") output.write(`${file}\n`);
|
|
284
|
+
else output.write(`${file.status.padEnd(8)} ${file.path}\n`);
|
|
270
285
|
}
|
|
271
286
|
}
|
|
272
287
|
if (value.checks) {
|
|
273
|
-
for (const check of value.checks)
|
|
288
|
+
for (const check of value.checks) output.write(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}\n`);
|
|
274
289
|
}
|
|
275
290
|
}
|
|
276
291
|
|
|
@@ -307,6 +322,13 @@ function launchUpdateRefresh(options, runner = spawn) {
|
|
|
307
322
|
async function main() {
|
|
308
323
|
try {
|
|
309
324
|
const options = parseArgs(process.argv.slice(2));
|
|
325
|
+
if (options.command === "setup") {
|
|
326
|
+
const { setup } = require("../lib/setup.js");
|
|
327
|
+
const result = await setup(options, { print });
|
|
328
|
+
if (result.cancelled) process.exitCode = 130;
|
|
329
|
+
else if (result.failed) process.exitCode = 2;
|
|
330
|
+
return;
|
|
331
|
+
}
|
|
310
332
|
let result;
|
|
311
333
|
if (options.command === "install") result = await install(options);
|
|
312
334
|
else if (options.command === "upgrade") result = await upgrade(options);
|
package/docs/architecture.md
CHANGED
|
@@ -218,6 +218,10 @@ into the shared checker. Because Pi has no blocking stop hook,
|
|
|
218
218
|
an invalid final marker causes at most one follow-up turn. Pi project trust is
|
|
219
219
|
managed by Pi, and external sandboxes must expose the global store.
|
|
220
220
|
|
|
221
|
+
Grok Bot does not emit those events. Its install is the shared skills,
|
|
222
|
+
`AGENTS.md`, and the recipe under `integrations/grok-bot/`. Skill registration
|
|
223
|
+
and shell commands are the integration. See [Grok Bot](grok-bot.md).
|
|
224
|
+
|
|
221
225
|
Configured standalone session-start hooks invoke `djournal pull --auto` before
|
|
222
226
|
loading active work. Explicit journal-sync prompt intent invokes a manual pull.
|
|
223
227
|
Close hooks invoke `djournal sync --auto --work <slug>`, whose transport ordering
|
|
@@ -263,6 +263,8 @@ Because the journal is Markdown, different harnesses can read the same memory:
|
|
|
263
263
|
|
|
264
264
|
- Codex can start the work.
|
|
265
265
|
- Claude Code can continue from the same spine and decisions.
|
|
266
|
+
- Pi and Grok Bot can read the same files and links. Grok Bot does this with
|
|
267
|
+
skills and the CLI, without session hooks.
|
|
266
268
|
- A future harness can inspect the same files and links.
|
|
267
269
|
|
|
268
270
|
The journal keeps continuity outside any one model context.
|
package/docs/grok-bot.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Grok Bot
|
|
2
|
+
|
|
3
|
+
Grok Bot is a supported djournal harness. It uses the same rules, skills, and
|
|
4
|
+
Markdown journal as Codex, Claude Code, and Pi. It does not have SessionStart
|
|
5
|
+
or Stop hooks, so compliance is the installed skills plus the `djournal` /
|
|
6
|
+
`journal` CLI. Do not add hook files for this harness.
|
|
7
|
+
|
|
8
|
+
## Hub and peers
|
|
9
|
+
|
|
10
|
+
A **Journal Hub** bot installs djournal, registers skills, and reviews shared
|
|
11
|
+
history. **Engineering bots** journal their own work. The hub is an
|
|
12
|
+
asynchronous reconciler:
|
|
13
|
+
|
|
14
|
+
- peers self-serve skills and CLI commands
|
|
15
|
+
- the hub runs share, sync, and conflict review when asked
|
|
16
|
+
- `local_only` work is not published unless someone explicitly shares it
|
|
17
|
+
|
|
18
|
+
The hub does not take over a peer's session and does not need to be in the
|
|
19
|
+
turn path for the peer to write an entry.
|
|
20
|
+
|
|
21
|
+
The in-repo recipe is [`integrations/grok-bot/`](../integrations/grok-bot/README.md).
|
|
22
|
+
It is the open-source distribution path. Public bot templates are not part of
|
|
23
|
+
this package and may be unavailable on some teams. Publishing a live hub is a
|
|
24
|
+
follow-up, done from an account that can create the bot.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
djournal install --harness grok-bot
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Aliases `grok` and `grokbot` normalize to `grok-bot`. `--all` includes it.
|
|
33
|
+
|
|
34
|
+
That install:
|
|
35
|
+
|
|
36
|
+
- copies `.agents/rules`, `.agents/skills`, and `.agents/adapters`
|
|
37
|
+
- writes the managed `AGENTS.md` block and `.djournal.json` project marker
|
|
38
|
+
- copies the recipe to `integrations/grok-bot/` and a marker README to
|
|
39
|
+
`.grokbot/`
|
|
40
|
+
|
|
41
|
+
It does not write `.codex/hooks.json`, `.claude/settings.json`, or
|
|
42
|
+
`.pi/extensions`. Uninstalling `grok-bot` removes only the djournal-owned
|
|
43
|
+
`.grokbot/` and `integrations/grok-bot/` files. Shared `.agents/` content stays
|
|
44
|
+
until a full uninstall, same as other harnesses.
|
|
45
|
+
|
|
46
|
+
Detection uses `--harness grok-bot` or an existing `.grokbot/` directory. A
|
|
47
|
+
`grok` executable is not treated as evidence.
|
|
48
|
+
|
|
49
|
+
`djournal doctor` reports the CLI, `.agents/` rules and skills, the project
|
|
50
|
+
marker, and the recipe files. Missing hooks are not a failure. The CLI check
|
|
51
|
+
stays informational when `djournal` is not on `PATH`, and the detail points at
|
|
52
|
+
`integrations/grok-bot/skill-registration.md`.
|
|
53
|
+
|
|
54
|
+
## Register skills
|
|
55
|
+
|
|
56
|
+
Grok Bot does not read `.agents/skills` automatically. Register each
|
|
57
|
+
`SKILL.md` with UpdateSkill using the ids in
|
|
58
|
+
[`integrations/grok-bot/skill-registration.md`](../integrations/grok-bot/skill-registration.md).
|
|
59
|
+
|
|
60
|
+
Rewrite command examples to `djournal <command> --target <project-root>` and
|
|
61
|
+
resolve rule paths from the install target and `STATE.md`. Sibling skill links
|
|
62
|
+
use `[Name](sand-workflow:<id>)`. Keep upstream skills free of machine-specific
|
|
63
|
+
paths.
|
|
64
|
+
|
|
65
|
+
Also register **Checkup with Journal Hub** from
|
|
66
|
+
[`integrations/grok-bot/checkup.md`](../integrations/grok-bot/checkup.md). The
|
|
67
|
+
getting-started prose asks for the project root, sync mode, which peers are
|
|
68
|
+
engineering bots, and the hub display name, one question at a time.
|
|
69
|
+
|
|
70
|
+
## Brief peers
|
|
71
|
+
|
|
72
|
+
Use [`integrations/grok-bot/peer-briefing.md`](../integrations/grok-bot/peer-briefing.md).
|
|
73
|
+
Peers should install or reuse the harness, run the journal skills, and call
|
|
74
|
+
the hub for checkup rather than for every journal write.
|
|
75
|
+
|
|
76
|
+
## Related docs
|
|
77
|
+
|
|
78
|
+
- [Installation and repository layouts](installation.md)
|
|
79
|
+
- [Harness adapter contract](../.agents/adapters/contract.md)
|
|
80
|
+
- [Uninstalling and reinstalling](uninstalling.md)
|
package/docs/installation.md
CHANGED
|
@@ -11,16 +11,125 @@ carry journal memory. The installed project gets harness integration plus a
|
|
|
11
11
|
npm install -g djournal
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
Then
|
|
15
|
-
equip:
|
|
14
|
+
Then open the interactive journal from your repository or journal workspace:
|
|
16
15
|
|
|
17
16
|
```bash
|
|
18
|
-
djournal
|
|
17
|
+
djournal
|
|
19
18
|
```
|
|
20
19
|
|
|
21
20
|
The package exposes both `djournal` and `journal` commands. They point to the
|
|
22
21
|
same CLI.
|
|
23
22
|
|
|
23
|
+
## Interactive journal
|
|
24
|
+
|
|
25
|
+
Run `djournal` or `journal` without arguments in an interactive terminal.
|
|
26
|
+
`djournal setup` remains supported; use `djournal setup --target /path/to/project`
|
|
27
|
+
to open another project. Use the arrow keys and Enter to choose an option.
|
|
28
|
+
|
|
29
|
+
Each new question or menu replaces the previous screen. The project header stays
|
|
30
|
+
visible, and new results, errors, and confirmation details appear above the next
|
|
31
|
+
prompt until you continue. Returning from an editor redraws the entry picker.
|
|
32
|
+
A mark of two offset journal pages and a bookmark heads the wizard, beside the
|
|
33
|
+
djournal wordmark. Search, filters, and smaller terminals use a small document
|
|
34
|
+
symbol and the wordmark.
|
|
35
|
+
`TERM=dumb` uses an ASCII version of the mark.
|
|
36
|
+
Menus show short labels and details for the highlighted item; long paths wrap
|
|
37
|
+
instead of widening the menu. The list height adapts to the terminal size.
|
|
38
|
+
Color is optional: `NO_COLOR=1 djournal` uses plain text, and selection and
|
|
39
|
+
checkbox markers remain visible without color.
|
|
40
|
+
|
|
41
|
+
- **List:** choose a work item, then open an entry in your editor, share, pull, sync, or bind an active item to
|
|
42
|
+
an agent session. Sharing marks the item; Sync copies it to the Git projection.
|
|
43
|
+
If synchronization is disabled, the wizard offers configuration first.
|
|
44
|
+
- **Recall:** search journal knowledge across work items and open matching
|
|
45
|
+
entries or work descriptions in your editor. Press Tab to adjust filters, or refresh/rebuild the search index from the Recall menu.
|
|
46
|
+
- **Status:** inspect the project's installation, integrations, and versions.
|
|
47
|
+
- **Install:** select Codex, Claude Code, Pi, Grok Bot, a custom combination, all
|
|
48
|
+
supported integrations, or instructions only. After installation, configure the project.
|
|
49
|
+
Existing integrations are retained on an already installed project.
|
|
50
|
+
- **Configure:** keep work local, share through the project repository, or use
|
|
51
|
+
a separate existing journal Git repository. Set automatic sync for standalone
|
|
52
|
+
mode and choose update notifications and their frequency. Current values are
|
|
53
|
+
defaults; review the proposed changes before saving.
|
|
54
|
+
- **Upgrade:** refresh installed project assets with the installed CLI version.
|
|
55
|
+
- **Update:** run the existing `update check` operation. If a newer CLI is
|
|
56
|
+
available, show the npm update command; the wizard does not install packages.
|
|
57
|
+
- **Doctor:** run the existing project health checks.
|
|
58
|
+
- **Uninstall:** remove one integration or all installed assets after confirmation.
|
|
59
|
+
Journal history is kept; modified installed files are preserved and reported.
|
|
60
|
+
|
|
61
|
+
Press **Escape** to go back to the parent menu from any prompt. From a work's
|
|
62
|
+
actions it returns to the work picker; from the entry picker it returns to that
|
|
63
|
+
work's actions. In an unfinished install, configuration, or work action, Escape
|
|
64
|
+
discards the pending answers and returns to the menu that launched it. At the
|
|
65
|
+
main menu, Escape stays there. Completed operations remain applied.
|
|
66
|
+
|
|
67
|
+
Menus also have Back and Exit choices. Use Space to toggle integrations in the
|
|
68
|
+
checkbox list; detected integrations start selected. Enter accepts the current
|
|
69
|
+
selection or displayed default. Ctrl-C, Ctrl-D, or end-of-input cancels. Completed operations remain applied, while
|
|
70
|
+
configuration answers are saved only after confirmation. A failed operation
|
|
71
|
+
returns to the main menu with an error; the process exits with code 2 if an
|
|
72
|
+
operation failed, or 130 on cancellation.
|
|
73
|
+
|
|
74
|
+
The wizard requires terminal input and output. An argument-free invocation in a
|
|
75
|
+
pipe or script returns an interactive-terminal error instead of waiting for input.
|
|
76
|
+
The explicit `setup` command accepts only `--target` and `--help`.
|
|
77
|
+
All existing commands continue to work directly, including JSON and dry runs.
|
|
78
|
+
Use `djournal --help` for the command list.
|
|
79
|
+
For example, `djournal install --all` installs directly without the wizard.
|
|
80
|
+
|
|
81
|
+
### Recall from the wizard
|
|
82
|
+
|
|
83
|
+
Choose **Recall → Search journal** and start typing. Results update in place
|
|
84
|
+
after a 250 ms pause; you do not need to submit the query. Use Up/Down to select
|
|
85
|
+
a result and Enter to open its canonical Markdown file in your editor. Close
|
|
86
|
+
the editor to return to the same query and refreshed results. Both entries and
|
|
87
|
+
work descriptions are searched, including completed work; the current session binding does not silently restrict the search.
|
|
88
|
+
|
|
89
|
+
Keep typing to change the query. Press **Tab** at any time to open the filter
|
|
90
|
+
panel, including while results load. All filters appear together: work item,
|
|
91
|
+
result kind, entry type, work status, visibility, and maximum results per kind.
|
|
92
|
+
Use **Up/Down** to choose a field and **Left/Right** to adjust it. On the result
|
|
93
|
+
limit row, you can also type a number from 1 to 100. **Enter** applies the draft
|
|
94
|
+
and returns to the same query; **Escape** discards it. **Ctrl-R** resets the draft
|
|
95
|
+
to defaults, which you can apply or discard.
|
|
96
|
+
|
|
97
|
+
The search screen shows the current scope and a compact, paged list of matches.
|
|
98
|
+
Filter controls are separate from matches. Previous matches remain dimmed while
|
|
99
|
+
updating and cannot be opened until the new search finishes. Blank queries skip
|
|
100
|
+
searching; Tab still opens filters and Escape returns to Recall.
|
|
101
|
+
|
|
102
|
+
**Refresh index** updates the cache from the journal. **Rebuild index** recreates
|
|
103
|
+
it after confirmation. These use the same services as `djournal recall index`
|
|
104
|
+
and `djournal recall index --rebuild`; they do not rewrite journal entries.
|
|
105
|
+
|
|
106
|
+
### Open journal entries in your editor
|
|
107
|
+
|
|
108
|
+
Choose **List → a work item → Open entry in editor**. The picker lists journal,
|
|
109
|
+
research, documentation, and decision entries, newest first, with their dates,
|
|
110
|
+
types, titles, and filenames. It reads the canonical journal store configured by
|
|
111
|
+
`.djournal.json`, with support for legacy local journals. Sharing does not need
|
|
112
|
+
to be enabled.
|
|
113
|
+
|
|
114
|
+
The editor is selected from `$VISUAL`, then `$EDITOR`, falling back to `vi`
|
|
115
|
+
(`notepad` on Windows). For example:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
export EDITOR='nano'
|
|
119
|
+
export VISUAL='vim -R'
|
|
120
|
+
djournal
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Quoted executable paths and arguments are supported, such as
|
|
124
|
+
`VISUAL='"/path with spaces/editor" --wait'`. Commands run directly; shell aliases,
|
|
125
|
+
pipes, variable expansion, and other shell expressions are not evaluated. Use a
|
|
126
|
+
waiting mode such as `code --wait` for an editor that otherwise returns immediately.
|
|
127
|
+
|
|
128
|
+
Close the editor to return to the entry picker. The canonical Markdown file is
|
|
129
|
+
opened directly, so saving edits changes the journal; use your editor's read-only
|
|
130
|
+
flag if desired. The wizard does not rewrite entry metadata. If an editor cannot
|
|
131
|
+
start or exits unsuccessfully, the picker remains available for retry or Escape.
|
|
132
|
+
|
|
24
133
|
## No global install
|
|
25
134
|
|
|
26
135
|
Use `npx` when you want a one-off install without adding a global command:
|
|
@@ -41,8 +150,9 @@ djournal install
|
|
|
41
150
|
This installs:
|
|
42
151
|
|
|
43
152
|
- shared journal rules and skills under `.agents/`
|
|
44
|
-
- harness-specific hook config when selected
|
|
153
|
+
- harness-specific hook config when a hook harness is selected
|
|
45
154
|
- a managed `.pi/extensions/djournal.ts` extension when Pi is selected
|
|
155
|
+
- a skill-only Journal Hub recipe and `.grokbot/` marker when Grok Bot is selected, with no hook config
|
|
46
156
|
- managed instruction blocks in `AGENTS.md` and/or `CLAUDE.md`
|
|
47
157
|
- `.djournal.json`, which points to the global project store
|
|
48
158
|
- for Claude Code installs, a narrow permission grant that lets the agent read
|
|
@@ -71,6 +181,14 @@ or RPC runs without a stored trust decision, pass `--approve`. djournal does not
|
|
|
71
181
|
edit Pi's trust file. Pi itself is not a filesystem sandbox; external containers
|
|
72
182
|
or sandboxes must expose the global store referenced by `.djournal.json`.
|
|
73
183
|
|
|
184
|
+
Grok Bot cannot run SessionStart or Stop hooks. `djournal install --harness
|
|
185
|
+
grok-bot` installs the portable skills, `AGENTS.md`, the project marker, and
|
|
186
|
+
the recipe at `integrations/grok-bot/`. It does not write `.codex/hooks.json`,
|
|
187
|
+
`.claude/settings.json`, or `.pi/extensions`. Register the skills in Grok from
|
|
188
|
+
that recipe. `djournal doctor` reports the CLI, `.agents/`, and the marker for
|
|
189
|
+
this harness and does not fail because hooks are absent. See
|
|
190
|
+
[Grok Bot](grok-bot.md).
|
|
191
|
+
|
|
74
192
|
To share selected work through the product repository, enable colocated
|
|
75
193
|
projection:
|
|
76
194
|
|
|
@@ -126,12 +244,15 @@ Install for one harness:
|
|
|
126
244
|
djournal install --harness codex
|
|
127
245
|
djournal install --harness claude-code
|
|
128
246
|
djournal install --harness pi
|
|
247
|
+
djournal install --harness grok-bot
|
|
129
248
|
```
|
|
130
249
|
|
|
250
|
+
`grok` and `grokbot` are aliases for `grok-bot`.
|
|
251
|
+
|
|
131
252
|
Install for multiple harnesses:
|
|
132
253
|
|
|
133
254
|
```bash
|
|
134
|
-
djournal install --harness codex,claude-code,pi
|
|
255
|
+
djournal install --harness codex,claude-code,pi,grok-bot
|
|
135
256
|
```
|
|
136
257
|
|
|
137
258
|
Install every supported harness:
|
|
@@ -158,7 +279,9 @@ djournal update check
|
|
|
158
279
|
project asset version, and cached npm release availability. `doctor` checks the
|
|
159
280
|
local environment and harness configuration. For Pi it reports extension
|
|
160
281
|
presence and reminds you that project trust is required; it does not inspect or
|
|
161
|
-
change Pi's private trust state.
|
|
282
|
+
change Pi's private trust state. For Grok Bot it reports the CLI, `.agents/`
|
|
283
|
+
skills and rules, the project marker, and recipe files, and points at skill
|
|
284
|
+
registration. Missing Grok hooks are expected and are not a failure.
|
|
162
285
|
|
|
163
286
|
## Update notifications
|
|
164
287
|
|
|
@@ -202,6 +325,7 @@ errors.
|
|
|
202
325
|
|
|
203
326
|
## Related docs
|
|
204
327
|
|
|
328
|
+
- [Grok Bot](grok-bot.md)
|
|
205
329
|
- [Remote Git sync setup](remote-sync.md)
|
|
206
330
|
- [Read-only team journal access](read-only-team-journal.md)
|
|
207
331
|
- [Uninstalling and reinstalling](uninstalling.md)
|
|
@@ -52,12 +52,13 @@ djournal status
|
|
|
52
52
|
|
|
53
53
|
Use `--instructions-only` when the person only needs portable journal skills and
|
|
54
54
|
does not need editor-specific hooks. Use a harness install instead when they
|
|
55
|
-
will use the journal from Codex, Claude Code, or
|
|
55
|
+
will use the journal from Codex, Claude Code, Pi, or Grok Bot:
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
58
|
djournal install --harness codex
|
|
59
59
|
djournal install --harness claude-code
|
|
60
60
|
djournal install --harness pi
|
|
61
|
+
djournal install --harness grok-bot
|
|
61
62
|
```
|
|
62
63
|
|
|
63
64
|
Do not run these commands in a read-only consumer setup:
|
package/docs/recall.md
CHANGED
package/docs/remote-sync.md
CHANGED
|
@@ -25,7 +25,7 @@ djournal config sync.mode colocated
|
|
|
25
25
|
djournal config sync.path .
|
|
26
26
|
djournal share --work 2026-07-03-01-example
|
|
27
27
|
djournal sync --work 2026-07-03-01-example
|
|
28
|
-
git add .agents .codex .claude AGENTS.md CLAUDE.md .djournal.json .journal
|
|
28
|
+
git add .agents .codex .claude .pi .grokbot integrations/grok-bot AGENTS.md CLAUDE.md .djournal.json .journal
|
|
29
29
|
git commit -m "chore: install djournal"
|
|
30
30
|
git push origin main
|
|
31
31
|
```
|