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.
@@ -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 portable handoff
24
- layer: each agent can read the same Markdown spine, follow the same decisions
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 install
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, or Pi. Select
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 Pi are supported. OpenCode and Zed adapters are planned.
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 selection
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 (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update", "work", "recall"].includes(command)) {
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
- process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
194
+ output.write(`${JSON.stringify(value, null, 2)}\n`);
188
195
  return;
189
196
  }
190
197
  if (value.action === "update-check") {
191
- process.stdout.write(`cli version: ${value.cliVersion || "unknown"}\n`);
192
- if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
193
- process.stdout.write(`latest version: ${value.latestVersion || "unknown"}\n`);
194
- if (value.updateAvailable) process.stdout.write(`update available: ${value.cliVersion} -> ${value.latestVersion}\n`);
195
- else if (value.latestVersion) process.stdout.write("djournal CLI is up to date\n");
196
- if (value.projectUpdateAvailable) process.stdout.write(`project upgrade available: ${value.projectVersion} -> ${value.cliVersion}\n`);
197
- if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
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) process.stdout.write(`selected: ${value.selected}\n`);
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
- process.stdout.write(`${marker} ${item.slug} [${item.status}] ${item.title}\n`);
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
- process.stdout.write(`bound ${value.work} to session ${value.sessionHash}\n`);
216
+ output.write(`bound ${value.work} to session ${value.sessionHash}\n`);
210
217
  return;
211
218
  }
212
219
  if (value.action === "recall-files") {
213
- process.stdout.write(`recall files: ${value.cache.status} (${value.cache.mode}), ${value.entries.length}/${value.totalEntries} entries\n`);
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
- process.stdout.write(`${entry.path} ${entry.title}\n`);
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
- process.stdout.write(` ${match.inputPath}: ${match.kind} — ${detail}\n`);
225
+ output.write(` ${match.inputPath}: ${match.kind} — ${detail}\n`);
219
226
  }
220
- for (const replacement of entry.supersededBy) process.stdout.write(` superseded by: ${replacement.path}\n`);
221
- if (entry.matchesTruncated || entry.codeReferencesTruncated || entry.supersededByTruncated) process.stdout.write(" additional entry evidence truncated\n");
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) process.stdout.write(`no indexed evidence: ${value.unmatchedPaths.join(", ")}\n`);
224
- if (value.truncated || value.relatedTruncated) process.stdout.write("results or linked context truncated; narrow paths or raise --limit\n");
225
- for (const item of value.warnings) process.stdout.write(`warning: ${item.code}\n`);
226
- process.stdout.write("Evidence candidates only; read canonical entries before assessing the change.\n");
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
- process.stdout.write(`recall index: ${value.cache.status} (${value.cache.mode})\n`);
231
- process.stdout.write(`documents: ${value.cache.documentCount}\n`);
232
- process.stdout.write(`elapsed: ${value.cache.totalMs.toFixed(1)} ms\n`);
233
- for (const item of value.warnings || []) process.stdout.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
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
- process.stdout.write(`recall search: ${value.cache.status} (${value.cache.mode}), ${value.cache.totalMs.toFixed(1)} ms\n`);
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
- process.stdout.write(`${item.score.toFixed(2).padStart(8)} ${item.path} ${item.title}\n`);
246
+ output.write(`${item.score.toFixed(2).padStart(8)} ${item.path} ${item.title}\n`);
240
247
  }
241
- for (const item of value.warnings || []) process.stdout.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
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) process.stdout.write(`${value.action}: ${value.target}\n`);
245
- else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
246
- else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
247
- if (value.harnesses) process.stdout.write(`harnesses: ${value.harnesses.join(", ") || "instructions-only"}\n`);
248
- if (value.key) process.stdout.write(`${value.key}: ${JSON.stringify(value.value)}\n`);
249
- else if (value.config) process.stdout.write(`${JSON.stringify(value.config, null, 2)}\n`);
250
- if (value.cliVersion) process.stdout.write(`cli version: ${value.cliVersion}\n`);
251
- if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
252
- if (value.latestVersion) process.stdout.write(`latest version: ${value.latestVersion}\n`);
253
- if (value.updateAvailable) process.stdout.write("update available: yes\n");
254
- if (value.projectUpdateAvailable) process.stdout.write("project upgrade available: yes\n");
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
- process.stdout.write(`recall cache: ${cache.valid ? `${cache.documentCount} documents, ${cache.indexVersion}` : (cache.exists ? "invalid; rebuilds on next recall" : "not built")}\n`);
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
- process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
262
- if (item.warning) process.stdout.write(`warning: ${item.warning}\n`);
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.conflicts?.length) process.stdout.write(`conflicts: ${value.conflicts.join(", ")}\n`);
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") process.stdout.write(`${file}\n`);
269
- else process.stdout.write(`${file.status.padEnd(8)} ${file.path}\n`);
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) process.stdout.write(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}\n`);
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);
@@ -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.
@@ -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)
@@ -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 run the installer from the repository or journal workspace you want to
15
- equip:
14
+ Then open the interactive journal from your repository or journal workspace:
16
15
 
17
16
  ```bash
18
- djournal install
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 Pi:
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
@@ -56,6 +56,7 @@ Install djournal for the agent harness you use:
56
56
  djournal install --harness codex
57
57
  # or: --harness claude-code
58
58
  # or: --harness pi
59
+ # or: --harness grok-bot
59
60
  ```
60
61
 
61
62
  Then ask naturally:
@@ -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
  ```