djournal 0.1.0 → 0.2.0

package/docs/djournal-in-practice.md

@@ -0,0 +1,246 @@
+# Djournal in Practice
+
+djournal works best when it records meaningful work as the work happens. It is
+not a transcript archive and not a replacement for code review. It is the
+reasoning layer that helps future people and agents resume from the right
+state.
+
+## Start or resume work
+
+At session start, the active work item gives the agent a compact context pack:
+
+- latest timeline
+- current state
+- linked decisions and research
+- next steps
+- recovery warnings from Git status
+
+This lets future sessions start from shaped history rather than broad
+exploration.
+
+## Plan before risky work
+
+Use a plan entry when the work has multiple phases, cross-component effects, or
+non-obvious validation:
+
+```text
+Plan the migration before changing code.
+```
+
+Plans should explain goals, non-goals, current state, design, phased steps,
+tests, edge cases, and open questions.
+
+You can ask explicitly:
+
+```text
+Plan the auth migration before changing code.
+```
+
+You can also describe the work without naming the skill:
+
+```text
+We need to migrate auth tokens from local storage to httpOnly cookies. Work out
+the phases, risks, tests, and rollout before implementation.
+```
+
+The agent should infer that a durable plan is useful because the request has
+multiple phases, security implications, rollout risk, and validation work. If
+the task is small and obvious, the agent may skip a durable plan and implement
+directly.
+
+## Capture evidence
+
+Use research entries when findings should survive the session:
+
+- how a subsystem works
+- type or schema discovery
+- integration maps
+- current external docs or standards
+- alternatives and tradeoffs
+
+Research should cite files, commands, links, and concrete observations. It
+should not paste entire source files or transcripts.
+
+You can ask explicitly:
+
+```text
+Research how billing webhooks are handled in this codebase.
+```
+
+Or:
+
+```text
+Before we change webhook retries, map the current webhook flow, tests, and
+places where failures are handled.
+```
+
+The agent should infer codebase research when the request asks for an
+implementation map, type discovery, integration analysis, dependency review,
+or current behavior before planning or changing code.
+
+## Record decisions
+
+Use decision entries when a choice constrains future work:
+
+- chosen architecture
+- rejected option and rationale
+- product behavior
+- migration policy
+- supersession of an older decision
+
+Good decisions make future debates shorter because they preserve the original
+constraints and evidence.
+
+You do not have to say the word "decision", but it is often the clearest way to
+ask:
+
+```text
+Decision: use a standalone journal repository for multi-repo product work.
+Record the rationale and consequences.
+```
+
+The agent should also infer a decision when the request clearly states that an
+option has been chosen:
+
+```text
+We are going with httpOnly cookies instead of local storage for auth tokens
+because XSS risk matters more than the extra CSRF handling. Capture that so we
+do not relitigate it later.
+```
+
+The agent should not create a decision entry for unresolved discussion:
+
+```text
+Compare local storage and httpOnly cookies for auth tokens.
+```
+
+That is research or a decision aid until a choice is actually made. A decision
+entry needs the context, options considered, chosen option, rationale,
+consequences, and follow-up. If those facts are missing, the agent should ask
+or record only the known state.
+
+## Write durable docs
+
+Use doc entries for synthesized references that should stand on their own:
+
+- architecture references
+- walkthroughs
+- how-to guides
+- onboarding notes
+- decision aids before a choice is made
+
+Explicit request:
+
+```text
+Document how journal sync works for future contributors.
+```
+
+Inferred request:
+
+```text
+Create a durable guide that explains the webhook retry system, including the
+current flow, operational concerns, and how to safely change it.
+```
+
+The agent should infer a doc entry when the requested output is a lasting
+reference, not just an answer in chat.
+
+## Close meaningful work
+
+After implementation or material status changes, write a spine entry that
+records:
+
+- what changed
+- why it changed
+- files touched
+- validation results
+- current state
+- next steps
+
+The latest spine entry becomes the primary resume index.
+
+Implementation and status entries are usually created at closure. You normally
+do not need to ask for them directly if the project uses djournal automation.
+When work changes code, docs, behavior, or material project state, the agent
+should close with a spine entry after validation.
+
+Examples:
+
+```text
+Add the webhook retry backoff and tests.
+```
+
+This should usually produce an implementation entry after the change is made
+and validated.
+
+```text
+Check whether the release PR is open and record where things stand.
+```
+
+This should usually produce a status entry if it changes durable project state
+or records a material checkpoint.
+
+Read-only or trivial requests should not create journal noise:
+
+```text
+What does this function do?
+Fix this typo.
+```
+
+Those may use recall or direct inspection, but they should not force a new
+entry unless they materially affect durable work state.
+
+## Skill names and inference
+
+djournal supports both explicit and inferred skill use.
+
+| User wording | Likely journal behavior |
+| --- | --- |
+| "Resume this work" | Read the active work item and latest spine entry. |
+| "Plan this migration" | Create a plan entry before implementation. |
+| "Research how auth works" | Create a codebase research entry. |
+| "Look up the current API docs and record findings" | Create web research with sources. |
+| "We chose option B; record why" | Create a decision entry. |
+| "Write a durable guide for this subsystem" | Create a doc entry. |
+| "Implement this feature" | Implement, validate, then create an implementation entry. |
+| "Record current blockers/status" | Create a status entry. |
+
+Explicit keywords make intent unambiguous, especially for decisions and docs.
+They are not required when the meaning is clear. The agent should infer from
+the request using the journal automation rules:
+
+- meaningful implementation gets resumed, validated, and journaled
+- durable research gets a research entry
+- accepted choices get decision entries
+- durable references get doc entries
+- read-only and trivial work avoid unnecessary entries
+
+If the request is ambiguous, the agent should ask a short clarifying question
+or choose the least surprising durable artifact.
+
+## Keep entries bounded
+
+Store durable facts, not raw session noise:
+
+- file paths, commands, test results, PRs, commits
+- concise rationale and summaries
+- links to supporting entries
+- short failure excerpts only when useful
+
+Avoid storing secrets, environment dumps, full transcripts, full diffs, or
+unbounded logs.
+
+## Use with multiple agents
+
+Because the journal is Markdown, different harnesses can read the same memory:
+
+- Codex can start the work.
+- Claude Code can continue from the same spine and decisions.
+- A future harness can inspect the same files and links.
+
+The journal keeps continuity outside any one model context.
+
+## Related docs
+
+- [Architecture and data model](architecture.md)
+- [Visibility and sharing](visibility-and-sharing.md)

package/docs/installation.md

@@ -0,0 +1,152 @@
+# Installation and Repository Layouts
+
+djournal can be installed globally and then added to each project that should
+carry journal memory. The installed project gets harness integration plus a
+`.djournal.json` marker. The canonical journal content lives under
+`~/.djournal/projects/<project-key>/`.
+
+## Recommended install
+
+```bash
+npm install -g djournal
+```
+
+Then run the installer from the repository or journal workspace you want to
+equip:
+
+```bash
+djournal install
+```
+
+The package exposes both `djournal` and `journal` commands. They point to the
+same CLI.
+
+## No global install
+
+Use `npx` when you want a one-off install without adding a global command:
+
+```bash
+npx djournal install
+```
+
+## Single-repository setup
+
+Use this when one product repository owns the work:
+
+```bash
+cd my-product
+djournal install
+```
+
+This installs:
+
+- shared journal rules and skills under `.agents/`
+- harness-specific hook config when selected
+- managed instruction blocks in `AGENTS.md` and/or `CLAUDE.md`
+- `.djournal.json`, which points to the global project store
+- for Claude Code installs, a narrow permission grant that lets the agent read
+  and write this project's global journal store and run safe `journal`/`djournal`
+  workflow commands
+
+The durable journal entries live under
+`~/.djournal/projects/<project-key>/.journal/work/...`.
+
+## Harness permissions
+
+Claude Code stores project permissions in `.claude/settings.json`, so
+`djournal install --harness claude-code` and `djournal install --all` add this
+project's exact global store path to `permissions.additionalDirectories` and
+allow the safe `journal`/`djournal` commands used by the workflow. Uninstall
+removes only the permission entries that djournal injected.
+
+Codex sandbox permissions are controlled by the Codex runtime launch/config
+rather than `.codex/hooks.json`. The installed Codex hook resolves the global
+store through `.djournal.json`; if the Codex session is sandboxed, launch it
+with the generated journal store path available as a readable/writable root.
+
+To share selected work through the product repository, enable colocated
+projection:
+
+```bash
+djournal config sync.enabled true
+djournal config sync.mode colocated
+djournal config sync.path .
+djournal share --work 2026-07-03-01-example
+djournal sync --work 2026-07-03-01-example
+```
+
+That copies the shared work item into `./.journal/work/...` so normal product
+repository commits can carry it.
+
+## Multi-repository setup
+
+Use standalone projection when one work stream spans several code repositories:
+
+```bash
+mkdir my-product-journal
+cd my-product-journal
+git init
+djournal install --all
+djournal config sync.enabled true
+djournal config sync.mode standalone
+djournal config sync.path .
+```
+
+Keep the journal repository as a sibling of the product repositories:
+
+```text
+workspace/
+  product-api/
+  product-web/
+  product-mobile/
+  my-product-journal/
+    .djournal.json
+    .journal/          # shared projection after djournal sync
+    .agents/
+```
+
+Agents can run from the workspace or journal repository as long as they resolve
+the installed project marker. Journal entries can still reference paths and
+commits in sibling code repositories.
+
+## Harness selection
+
+Install for one harness:
+
+```bash
+djournal install --harness codex
+djournal install --harness claude-code
+```
+
+Install for multiple harnesses:
+
+```bash
+djournal install --harness codex,claude-code
+```
+
+Install every supported harness:
+
+```bash
+djournal install --all
+```
+
+Install only the portable instructions and journal skills:
+
+```bash
+djournal install --instructions-only
+```
+
+## Useful checks
+
+```bash
+djournal status
+djournal doctor
+```
+
+`status` reports installed files and cleanliness. `doctor` checks the local
+environment and harness configuration.
+
+## Related docs
+
+- [Remote Git sync setup](remote-sync.md)
+- [Uninstalling and reinstalling](uninstalling.md)

package/docs/remote-sync.md

@@ -0,0 +1,144 @@
+# Remote Git Sync Setup
+
+Git-backed sharing lets a team move journal history through the same reviewable
+transport they use for code. There are two different modes:
+
+- colocated `.journal/` in a product repository
+- standalone journal repository for multi-repo or team-wide memory
+
+The `djournal sync` command is opt-in and intended for standalone journal
+repositories or colocated projections. The canonical journal stays in
+`~/.djournal/projects/<project-key>/`; sync copies explicitly shared work into
+the configured Git-backed projection.
+
+## Colocated repository
+
+Use colocated mode when the product repository should carry `.journal/` beside
+the code:
+
+```bash
+cd my-product
+djournal install --all
+djournal config sync.enabled true
+djournal config sync.mode colocated
+djournal config sync.path .
+djournal share --work 2026-07-03-01-example
+djournal sync --work 2026-07-03-01-example
+git add .agents .codex .claude AGENTS.md CLAUDE.md .djournal.json .journal
+git commit -m "chore: install djournal"
+git push origin main
+```
+
+Only share journal work that is safe for the team to see. In colocated mode,
+`djournal share` updates the global sharing index and `djournal sync` projects
+that work into the repository `.journal/`. Git publication then happens through
+normal product commits.
+
+If `.journal/` or `.journal/work/...` is ignored, projection can still create
+files locally, but Git will not include them unless you update `.gitignore` or
+force-add the intended path:
+
+```bash
+git add -f .journal/work/2026-07-03-01-example
+```
+
+## Standalone journal repository
+
+Use a standalone journal repository when work spans multiple code repositories:
+
+```bash
+mkdir my-product-journal
+cd my-product-journal
+git init
+djournal install --all
+djournal config sync.enabled true
+djournal config sync.mode standalone
+djournal config sync.path .
+djournal config sync.auto true
+git remote add origin git@github.com:example/my-product-journal.git
+git add .
+git commit -m "chore: bootstrap journal"
+git push -u origin main
+```
+
+Keep the repository next to the code repositories and point `sync.path` at it
+from the workspace/project that owns the global journal store.
+
+## Bootstrapping from an existing remote
+
+When the journal remote already exists:
+
+```bash
+git clone git@github.com:example/my-product-journal.git
+cd my-product-journal
+djournal install --all
+djournal status
+```
+
+If `.journal/` is already present after clone, the install step refreshes local
+harness integration without replacing durable journal history.
+
+If the remote was created for standalone journal sync, verify config with
+`djournal config` before expecting hooks to synchronize automatically.
+
+## Sharing a work item
+
+By default, work is local-only. Promote a work item before publishing its
+journal history:
+
+```bash
+djournal share
+```
+
+Select a specific work item:
+
+```bash
+djournal share --work 2026-07-03-01-git-backed-journal-collaboration
+```
+
+Sharing is a publication intent recorded in the global config. Treat it as
+durable: once projected content has been pushed to a team remote, removing it
+from the sharing index does not remove it from Git history or teammates' clones.
+
+## Synchronizing shared work
+
+Run sync manually:
+
+```bash
+djournal sync
+```
+
+Or select a work item:
+
+```bash
+djournal sync --work 2026-07-03-01-git-backed-journal-collaboration
+```
+
+Current behavior:
+
+- sync is skipped unless global `config.json` opts in
+- unshared work is skipped
+- colocated mode copies shared work into the configured product repo projection
+- standalone mode copies shared work and then uses conservative Git operations
+- unresolved journal conflicts stop sync
+
+Hook-triggered sync uses the same command path with `--auto` only when
+global config enables standalone automatic sync and the closed work is shared.
+
+## Keep local state local
+
+Do not use Git as a blind mirror of every operational file. Treat these as
+local operational state unless a future workflow explicitly says otherwise:
+
+- `.journal/state.json`
+- `.journal/.install/`
+- `.djournal.json` when the team does not want to share the local store pointer
+- local harness cache or runtime files
+
+The durable team memory is the work item content: `work.md`, `journal/`,
+`decisions/`, `docs/`, and `_research/`.
+
+## Related docs
+
+- [Visibility and sharing](visibility-and-sharing.md)
+- [Architecture and data model](architecture.md)

package/docs/uninstalling.md

@@ -0,0 +1,78 @@
+# Uninstalling and Reinstalling
+
+Uninstall removes djournal tooling from selected harnesses while preserving
+durable journal history.
+
+## Uninstall everything
+
+```bash
+djournal uninstall --all
+```
+
+or:
+
+```bash
+djournal uninstall
+```
+
+Full uninstall removes managed instruction blocks, copied rules/skills, hook
+configuration owned by djournal, and installer metadata when it is safe to do
+so.
+
+## Uninstall one harness
+
+```bash
+djournal uninstall --harness codex
+djournal uninstall --harness claude-code
+```
+
+## Uninstall multiple harnesses
+
+```bash
+djournal uninstall --harness codex,claude-code
+```
+
+Partial uninstall removes only the selected harness integration and keeps the
+remaining harnesses installed.
+
+## What remains durable
+
+Uninstall preserves `.journal/` so work history can be revived later:
+
+```text
+.journal/
+  state.json
+  work/<work-item>/
+```
+
+That means plans, decisions, docs, research, implementation notes, and status
+entries remain available for future recall.
+
+## Reinstall later
+
+```bash
+djournal install --all
+```
+
+or select a harness:
+
+```bash
+djournal install --harness codex
+```
+
+Reinstalling restores local harness integration around the existing journal
+history.
+
+## Conflict behavior
+
+djournal preserves user edits. If a managed file has been modified outside the
+expected managed block or copied assets no longer match their installed hash,
+upgrade or uninstall may refuse to rewrite that file automatically.
+
+Use `djournal status` and `djournal doctor` to inspect the installation before
+and after uninstalling.
+
+## Related docs
+
+- [Installation and repository layouts](installation.md)
+- [Remote Git sync setup](remote-sync.md)

package/docs/visibility-and-sharing.md

@@ -0,0 +1,88 @@
+# Visibility and Sharing
+
+Visibility answers who the work is intended for. Sharing answers whether a work
+item should be projected out of the private global store into a Git-backed
+location. They are related but no longer the same control.
+
+## Visibility values
+
+| Visibility | Meaning |
+| --- | --- |
+| `local_only` | Default. Keep the work on the local machine. |
+| `private_synced` | Reserved compatibility state for private synchronized work. |
+| `team_shared` | Eligible for team sharing and Git-backed sync. |
+
+New work starts as `local_only` and unshared.
+
+## Sharing a work item
+
+Mark the active work item as shared:
+
+```bash
+djournal share
+```
+
+Mark a specific work item as shared:
+
+```bash
+djournal share --work 2026-07-03-01-git-backed-journal-collaboration
+```
+
+Dry run:
+
+```bash
+djournal share --dry-run --json
+```
+
+`share` updates `sharing.sharedWorkItems` in the global project config. It does
+not edit `work.md` visibility and does not by itself guarantee remote
+publication. Publication requires `djournal sync` plus the relevant Git commit
+or push for the configured mode.
+
+## Sync and visibility
+
+Run sync:
+
+```bash
+djournal sync
+```
+
+If the selected work item has not been shared, sync skips it:
+
+```json
+{
+  "action": "sync",
+  "skipped": true,
+  "reason": "work is not shared"
+}
+```
+
+For shared work, sync is still opt-in through global config:
+
+```bash
+djournal config sync.enabled true
+djournal config sync.mode colocated
+djournal sync
+```
+
+In colocated mode, sync copies shared work into the product repository
+projection. In standalone mode, sync copies shared work into the standalone
+journal repository and performs conservative Git operations.
+
+## Safety model
+
+Treat sharing as a durable escalation. After projected journal content enters a
+shared Git remote, it may remain in Git history and teammates' clones even if
+local sharing metadata changes later.
+
+Before sharing, check for:
+
+- customer or private data
+- secrets, credentials, tokens, and connection strings
+- private implementation details not intended for the team
+- accidental transcript dumps or unbounded logs
+
+## Related docs
+
+- [Remote Git sync setup](remote-sync.md)
+- [Uninstalling and reinstalling](uninstalling.md)