djournal 0.1.0 → 0.3.0

package/README.md

@@ -1,26 +1,67 @@
 # djournal
 
-Durable project memory for coding agents, readable by humans.
+Portable project memory for coding agents, readable by humans.
 
-djournal records the path of the work—plans, research, decisions, changes, and
-next steps—as linked Markdown inside your project. Codex and Claude Code can use
-that memory automatically across sessions without a database, account, or
-proprietary service.
+djournal records the reasoning path of the work: plans, research, decisions,
+changes, validation, and next steps. It lets you start in Codex, continue in
+Claude Code, switch models, survive context compaction, and still reload the
+same project state from plain Markdown.
+
+Code preserves what exists. djournal preserves why it exists.
 
 > **Files are memory. Indexes are projections.**
 
 ## Why djournal exists
 
-Code preserves what a system does. It rarely preserves why it became that way,
-what was tried, which evidence mattered, or what should happen next.
+djournal is built for product and engineering work that moves across sessions,
+models, people, and tools.
+
+### Continue across tools
+
+Long coding sessions do not survive tool boundaries well when the only handoff
+format is a transcript. A useful session may start in Codex, continue in Claude
+Code, and later resume somewhere else. The journal is the portable handoff
+layer: each agent can read the same Markdown spine, follow the same decisions
+and research links, and close its work in the same structure.
+
+The memory belongs to the project, not to a chat session, model, harness,
+database, or proprietary service.
+
+### Preserve the reasoning code cannot show
+
+Code shows what a system does. It rarely shows why it became that way, what was
+tried, which constraints mattered, which options were rejected, or what should
+happen next.
+
+Chat history preserves too much, with weak structure and poor portability.
+Conventional documentation usually captures polished outcomes after the fact.
+Static analysis can inspect the code as it is, but it cannot reliably recover
+the historical decisions that shaped it.
+
+djournal records that missing layer while the work happens.
+
+### Share institutional knowledge
+
+In AI-accelerated teams, traditional documentation can become stale almost as
+soon as it is written. Product specs, implementation notes, and architectural
+rationale need to be produced as a by-product of product and engineering work,
+not as a separate ritual.
+
+djournal gives that by-product a durable shape. The same entries that let an
+agent resume work also become institutional knowledge: reviewable by humans,
+searchable with ordinary tools, versioned through Git, and recallable by
+whichever model or harness the team uses next.
+
+### Let memory compound
 
-Chat transcripts preserve too much. Conventional documentation is usually
-written too late. Retrieval systems can find fragments, but they cannot recover
-reasoning that was never recorded.
+A journal can start from nothing. The first entries are mostly orientation:
+current state, open questions, and next steps. As the work accumulates, resume
+behavior changes. The agent is no longer guessing from a cold codebase or
+wandering through broad exploration. It reloads a shaped history: what mattered
+before, what was decided, what remains unresolved, and where the next useful
+move probably is.
 
-djournal makes project memory part of doing the work. Skills capture durable
-context when work becomes meaningful; optional hooks make the workflow
-default-on without writing entries behind the agent's back.
+The journal turns past work into focused guidance.
 
 ## Manifesto
 
@@ -33,42 +74,10 @@ default-on without writing entries behind the agent's back.
 4. **Structure should be sufficient, not maximal.** YAML carries stable
    metadata; Markdown carries meaning; links carry relationships.
 5. **Tools should remain replaceable.** Memory must survive changes in models,
-   agent harnesses, databases, and vendors.
+   agent harnesses, databases, vendors, and retrieval systems.
 6. **The workflow should carry the burden.** Maintaining memory should be a
    consequence of meaningful work, not another ritual to remember.
 
-## Why plain Markdown
-
-Markdown is immediately useful. It can be read before an ingestion pipeline
-runs, searched with ordinary tools, loaded selectively, reviewed line by line,
-and versioned with Git. Frontmatter makes important fields deterministic while
-links turn the directory into an explicit graph.
-
-Google Cloud's draft [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
-formalizes the same broad pattern: knowledge as linked Markdown with YAML
-frontmatter, portable through Git and independent of the tools that produce or
-consume it. djournal is conceptually aligned with that direction, but uses a
-domain-specific schema for project history and is not currently
-[OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
-conformant.
-
-## Why not only RAG or a knowledge graph?
-
-RAG, embeddings, full-text indexes, and graph views are useful retrieval tools.
-They are not ideal as the only durable copy of project memory.
-
-| Layer | What it provides |
-| --- | --- |
-| djournal Markdown | Canonical meaning, provenance, chronology, and links |
-| Git | Review, attribution, history, and team exchange |
-| Embeddings / RAG | Semantic retrieval over larger corpora |
-| Graph projection | Traversal, visualization, and multi-hop retrieval |
-
-Vector and graph indexes are derived representations: they require ingestion,
-can become stale, and may change with the model or extraction pipeline. djournal
-keeps the authored source inspectable and lets those indexes be rebuilt when
-needed. It complements retrieval infrastructure rather than replacing it.
-
 ## What djournal records
 
 ```text
@@ -85,6 +94,8 @@ needed. It complements retrieval infrastructure rather than replacing it.
 Entries carry structured frontmatter, stable identities, summaries, timestamps,
 and typed links. Markdown remains the source of truth.
 
+See [spec.md](spec.md) for the complete data model and workflow contracts.
+
 ## How it works
 
 ```mermaid
@@ -105,48 +116,125 @@ flowchart LR
 - Hooks never create or modify semantic journal entries.
 - Read-only and trivial requests do not generate unnecessary ceremony.
 
+## Why plain Markdown and Git
+
+Markdown is immediately useful. It can be read before an ingestion pipeline
+runs, searched with ordinary tools, loaded selectively, reviewed line by line,
+and versioned with Git. Frontmatter makes important fields deterministic while
+links turn the directory into an explicit graph.
+
+Git already distributes code history. djournal lets teams preserve reasoning
+history in the same reviewable medium: who changed the memory, when it changed,
+what it referenced, and how it evolved. That makes institutional knowledge easy
+for people to inspect and easy for agents to recall.
+
+Google Cloud's draft [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
+formalizes the same broad pattern: knowledge as linked Markdown with YAML
+frontmatter, portable through Git and independent of the tools that produce or
+consume it. djournal is conceptually aligned with that direction, but uses a
+domain-specific schema for project history and is not currently
+[OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+conformant.
+
+## Why not only RAG or a knowledge graph?
+
+RAG, embeddings, full-text indexes, and graph views are useful retrieval tools.
+They are not ideal as the only durable copy of project memory.
+
+| Layer | What it provides |
+| --- | --- |
+| djournal Markdown | Canonical meaning, provenance, chronology, and links |
+| Git | Review, attribution, history, and team exchange |
+| Embeddings / RAG | Semantic retrieval over larger corpora |
+| Graph projection | Traversal, visualization, and multi-hop retrieval |
+
+Vector and graph indexes are derived representations: they require ingestion,
+can become stale, and may change with the model or extraction pipeline. djournal
+keeps the authored source inspectable and lets those indexes be rebuilt when
+needed. It complements retrieval infrastructure rather than replacing it.
+
+Large context windows help, but they do not replace authored memory. A million
+tokens can hold more text; the agent still needs to know what matters.
+
 ## Install
 
 Requires Node.js 18 or newer. Run this from the project you want to equip:
 
 ```bash
-npx djournal install
+npm install -g djournal
+djournal install
 ```
 
-The installer targets the current directory and detects Codex or Claude Code.
-Select explicitly when needed:
+The global install gives you the `djournal` and `journal` commands. The
+installer targets the current directory and detects Codex or Claude Code. Select
+explicitly when needed:
 
 ```bash
-npx djournal install --harness codex
-npx djournal install --harness claude-code
-npx djournal install --all
+djournal install --harness codex
+djournal install --harness claude-code
+djournal install --all
+```
+
+If you do not want a global install, use `npx`:
+
+```bash
+npx djournal install
 ```
 
 Then use your coding agent normally.
 
+Install creates a local project marker (`.djournal.json`) and a canonical
+per-project store under `~/.djournal/projects/<project-key>/`:
+
+```text
+~/.djournal/projects/<project-key>/
+  config.json
+  .journal/
+```
+
+The project store is the private write target. A repository `.journal/` or
+standalone journal repo is a projection that receives shared work only after
+you opt in.
+
+For Claude Code, install also grants the project access to that exact global
+store path in `.claude/settings.json`, plus the safe `journal`/`djournal`
+commands used by the workflow. Codex uses runtime sandbox configuration for
+filesystem access, so sandboxed Codex sessions must include the generated store
+path when they need canonical journal memory.
+
 ## Lifecycle
 
 ```bash
-npx djournal status
-npx djournal doctor
-npx djournal upgrade
-npx djournal uninstall
+djournal status
+djournal doctor
+djournal config sync.enabled true
+djournal share --all
+djournal share
+djournal sync
+djournal upgrade
+djournal uninstall
 ```
 
 Installation preserves existing agent configuration. Uninstallation removes
-djournal's tooling while retaining `.journal/` so the project memory can be
-revived later.
+djournal's tooling while retaining durable project memory and the project
+marker so the journal can be revived later.
 
 Existing `AGENTS.md` and `CLAUDE.md` files are never replaced. djournal adds an
 owned block, updates only that block, and removes only that block during
 uninstall; surrounding project instructions remain untouched.
 
-See [spec.md](spec.md) for the complete data model and workflow contracts.
+`share` marks the active work item in the global sharing index. `sync` is
+opt-in; in colocated mode it projects shared work into the product repository
+for normal commits, and in standalone mode it projects shared work into a
+dedicated journal repository.
 
 ## Status
 
 Codex and Claude Code are supported. OpenCode, Pi, and Zed adapters are planned.
 
+Git-backed sharing and automatic sync are opt-in so local-only work remains
+private by default.
+
 ## Contributing and releases
 
 Pull request titles use Conventional Commit form, such as
@@ -156,3 +244,12 @@ Pull request titles use Conventional Commit form, such as
 increment the major version.
 
 djournal is licensed under the [Apache License 2.0](LICENSE).
+
+## Documentation
+
+- [Installation and repository layouts](docs/installation.md)
+- [Remote Git sync setup](docs/remote-sync.md)
+- [Architecture and data model](docs/architecture.md)
+- [Visibility and sharing](docs/visibility-and-sharing.md)
+- [Djournal in practice](docs/djournal-in-practice.md)
+- [Uninstalling and reinstalling](docs/uninstalling.md)

package/bin/journal.js

@@ -5,8 +5,11 @@
 const path = require("node:path");
 const {
   InstallerError,
+  configure,
   doctor,
   install,
+  share,
+  sync,
   status,
   uninstall,
   upgrade,
@@ -21,13 +24,17 @@ function usage() {
   journal uninstall [--target DIR] [--harness LIST | --all]
   journal status [--target DIR] [--json]
   journal doctor [--target DIR] [--json]
+  journal config [--target DIR] [KEY [VALUE]] [--dry-run] [--json]
+  journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
+  journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
 
 Options:
   --dry-run             Show the planned operation without writing
   --yes                 Disable interactive harness selection
   --json                Emit JSON
+  --work SLUG           Select a journal work item instead of active state
   --harness LIST        Comma-separated codex,claude-code selection
-  --all                 Select or remove every supported harness
+  --all                 Select all work items for share, or every harness
   --instructions-only   Install core instructions without harness hooks
 `;
 }
@@ -35,7 +42,7 @@ Options:
 function parseArgs(argv) {
   const args = [...argv];
   const command = args.shift();
-  if (!command || !["install", "upgrade", "uninstall", "status", "doctor"].includes(command)) {
+  if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "sync"].includes(command)) {
     throw new InstallerError(usage(), "USAGE");
   }
   const options = { command, harnesses: [] };
@@ -45,6 +52,10 @@ function parseArgs(argv) {
       if (!args.length) throw new InstallerError("--target requires a value", "USAGE");
       options.target = args.shift();
     } else if (arg.startsWith("--target=")) options.target = arg.slice(9);
+    else if (arg === "--work") {
+      if (!args.length) throw new InstallerError("--work requires a value", "USAGE");
+      options.work = args.shift();
+    } else if (arg.startsWith("--work=")) options.work = arg.slice(7);
     else if (arg === "--harness") {
       if (!args.length) throw new InstallerError("--harness requires a value", "USAGE");
       options.harnesses.push(...args.shift().split(",").filter(Boolean));
@@ -52,12 +63,19 @@ function parseArgs(argv) {
     else if (arg === "--all") options.all = true;
     else if (arg === "--instructions-only") options.instructionsOnly = true;
     else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--auto") options.auto = true;
     else if (arg === "--yes") options.yes = true;
     else if (arg === "--json") options.json = true;
     else if (arg === "--help" || arg === "-h") throw new InstallerError(usage(), "HELP");
+    else if (command === "config" && !options.key) options.key = arg;
+    else if (command === "config" && typeof options.value === "undefined") options.value = arg;
     else throw new InstallerError(`unknown option: ${arg}`, "USAGE");
   }
   if (options.all && options.harnesses.length) throw new InstallerError("use either --all or --harness", "USAGE");
+  if (options.all && options.work) throw new InstallerError("use either --all or --work", "USAGE");
+  if (options.all && !["install", "uninstall", "share"].includes(command)) {
+    throw new InstallerError(`--all is not supported for ${command}`, "USAGE");
+  }
   if (options.instructionsOnly && (options.all || options.harnesses.length)) {
     throw new InstallerError("--instructions-only cannot be combined with harness selection", "USAGE");
   }
@@ -76,6 +94,14 @@ function print(value, json) {
   else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
   else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
   if (value.harnesses) process.stdout.write(`harnesses: ${value.harnesses.join(", ") || "instructions-only"}\n`);
+  if (value.key) process.stdout.write(`${value.key}: ${JSON.stringify(value.value)}\n`);
+  else if (value.config) process.stdout.write(`${JSON.stringify(value.config, null, 2)}\n`);
+  if (value.workItems) {
+    for (const item of value.workItems) {
+      process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
+      if (item.warning) process.stdout.write(`warning: ${item.warning}\n`);
+    }
+  }
   if (value.conflicts?.length) process.stdout.write(`conflicts: ${value.conflicts.join(", ")}\n`);
   if (value.files) {
     for (const file of value.files) process.stdout.write(`${file.status.padEnd(8)} ${file.path}\n`);
@@ -101,6 +127,9 @@ async function main() {
     else if (options.command === "upgrade") result = await upgrade(options);
     else if (options.command === "uninstall") result = uninstall(options);
     else if (options.command === "status") result = status(options);
+    else if (options.command === "config") result = configure(options);
+    else if (options.command === "share") result = share(options);
+    else if (options.command === "sync") result = sync(options);
     else result = doctor(options);
     print(result, options.json);
     if (result.ok === false || result.installed === false || result.clean === false || result.conflicts?.length) process.exitCode = 2;

package/docs/architecture.md

@@ -0,0 +1,175 @@
+# Architecture and Data Model
+
+djournal is a filesystem journal. Markdown is the source of truth; indexes,
+RAG systems, graph views, and model context are projections over that source.
+
+## Directory layout
+
+The canonical journal lives in the user's djournal home, keyed by project:
+
+```text
+~/.djournal/projects/<project-key>/
+  config.json
+  .journal/
+    state.json
+    work/<work-item>/
+      work.md
+      journal/
+      decisions/
+      docs/
+      _research/
+```
+
+The installed project contains a marker that points back to that store:
+
+```text
+.djournal.json
+```
+
+When sync is enabled, a repository-local `.journal/` is a projection containing
+the shared work items copied out of the global store.
+
+```text
+<projection-target>/
+  .journal/
+    work/<shared-work-item>/
+```
+
+## Work items
+
+A work item is a durable unit of product or engineering work. It may span
+repositories, branches, harnesses, and models.
+
+Every work item has:
+
+```text
+~/.djournal/projects/<project-key>/.journal/work/<slug>/work.md
+```
+
+The frontmatter stores stable identity, title, status, visibility, authorship,
+and timestamps.
+
+## Configuration
+
+`config.json` is a sibling of the global `.journal/` directory. It stores
+project identity, sync settings, and the sharing index. Sync is disabled unless
+configuration opts in:
+
+```json
+{
+  "project": {
+    "id": "my-product-a1b2c3d4",
+    "name": "my-product",
+    "sourcePath": "/workspace/my-product"
+  },
+  "sync": {
+    "enabled": true,
+    "mode": "colocated",
+    "path": "/workspace/my-product",
+    "auto": false
+  },
+  "sharing": {
+    "default": "local_only",
+    "sharedWorkItems": {}
+  }
+}
+```
+
+Use the CLI to change it:
+
+```bash
+djournal config sync.enabled true
+djournal config sync.mode colocated
+djournal config sync.path /workspace/my-product
+```
+
+Use `mode: "standalone"` for a dedicated journal repository. Use
+`mode: "colocated"` when shared work should be projected into the product
+repository and published by normal product commits.
+
+## Entry types
+
+| Directory | Entry types | Role |
+| --- | --- | --- |
+| `journal/` | `plan`, `implementation`, `status`, `manual` | Spine |
+| `decisions/` | `decision` | Supporting |
+| `docs/` | `doc` | Supporting |
+| `_research/` | `research` | Supporting |
+
+The spine is the chronological project timeline. Supporting entries are durable
+evidence and references linked from the spine or from each other.
+
+## Frontmatter
+
+Entries use YAML frontmatter for stable metadata:
+
+```yaml
+---
+id: ent_...
+workItemId: wi_...
+entryType: implementation
+entryNumber: 7
+title: Implement README overhaul
+summary: Rewrote README.md around portable project memory.
+createdBy: person@example.com
+createdAt: "2026-07-07T20:03:30.906Z"
+updatedAt: "2026-07-07T20:03:30.906Z"
+source: manual
+---
+```
+
+The Markdown body carries the human-readable meaning. Frontmatter keeps lookup,
+sorting, identity, and link resolution deterministic.
+
+## Links
+
+Links are typed objects in frontmatter:
+
+```yaml
+links:
+  - id: lnk_...
+    fromEntryId: ent_...
+    toEntryId: ent_...
+    relation: references
+    createdAt: "2026-07-08T08:00:00.000Z"
+    targetPath: ../docs/example.md
+```
+
+Supported relations:
+
+- `references`: source uses target as evidence or context
+- `relates_to`: source is loosely connected to target
+- `supersedes`: newer entry replaces or rolls back an older entry
+
+## Decisions, docs, and research
+
+Decision entries record accepted choices, rationale, consequences, and
+supersession.
+
+Doc entries synthesize durable reference material such as architecture notes,
+how-tos, and product explanations.
+
+Research entries capture codebase or web findings with sources and open
+questions.
+
+## Hooks and skills
+
+`AGENTS.md` gives agents portable instructions. Skills perform journal-aware
+work such as resume, planning, research, decision capture, documentation,
+audit, reconciliation, and closure.
+
+Hooks remind agents about the workflow and validate final status markers. Hooks
+do not create semantic journal entries. When `.djournal.json` exists, hooks read
+active work and sync config from the global project store.
+
+For Claude Code, install also injects a narrow permission grant into
+`.claude/settings.json` for the exact global project store path and safe
+`journal`/`djournal` commands. Codex filesystem access is governed by the Codex
+runtime sandbox, so Codex sessions must be launched with the global store path
+available when sandboxing would otherwise hide `~/.djournal`.
+
+## Related docs
+
+- [Djournal in practice](djournal-in-practice.md)
+- [Visibility and sharing](visibility-and-sharing.md)
+- [spec.md](../spec.md)