djournal 0.5.1 → 0.7.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.
@@ -0,0 +1,150 @@
1
+ # Read-Only Team Journal Access
2
+
3
+ This guide is for people who need to read, recall, and research team journal
4
+ history without publishing their own journal entries back to the shared remote.
5
+ Typical users include PMs, designers, support leads, and executives who want to
6
+ ask an agent about prior decisions without learning the full synchronization
7
+ workflow.
8
+
9
+ ## Current Model
10
+
11
+ djournal does not yet have a single `connect --read-only` command. Today, a
12
+ read-only setup is achieved by combining three controls:
13
+
14
+ - Git credentials that can clone and pull the team journal repository but cannot
15
+ push to it.
16
+ - djournal sync config that enables `pull` but does not enable automatic
17
+ publication.
18
+ - Agent prompts that ask for read-only skills such as `recall`, `research`, and
19
+ `document`, not implementation or journal closure.
20
+
21
+ This still writes local files under the user's djournal home. "Read-only" means
22
+ read-only with respect to the organization remote, not a filesystem mode that
23
+ prevents local cache or canonical-store hydration.
24
+
25
+ ## Setup for a Non-Technical Reader
26
+
27
+ Ask the organization admin for the team journal repository URL and read-only Git
28
+ access. Then use this script-like sequence in a terminal from a working folder:
29
+
30
+ ```bash
31
+ npm install -g djournal
32
+ git clone <team-journal-repository-url> team-journal
33
+ cd team-journal
34
+ djournal install --instructions-only
35
+ djournal config sync.enabled true
36
+ djournal config sync.mode standalone
37
+ djournal config sync.path .
38
+ djournal config sync.auto false
39
+ djournal pull
40
+ djournal status
41
+ ```
42
+
43
+ Use `--instructions-only` when the person only needs portable journal skills and
44
+ does not need editor-specific hooks. Use a harness install instead when they
45
+ will use the journal from Codex, Claude Code, or Pi:
46
+
47
+ ```bash
48
+ djournal install --harness codex
49
+ djournal install --harness claude-code
50
+ djournal install --harness pi
51
+ ```
52
+
53
+ Do not run these commands in a read-only consumer setup:
54
+
55
+ ```bash
56
+ djournal share
57
+ djournal sync
58
+ ```
59
+
60
+ If read-only Git permissions are configured correctly, accidental pushes should
61
+ fail at the remote even if someone runs a publication command.
62
+
63
+ ## Copy/Paste Agent Prompt
64
+
65
+ Use this prompt after installation when asking an LLM agent to connect the local
66
+ checkout to the remote journal in read-only mode:
67
+
68
+ ```text
69
+ Set up djournal for read-only team journal access.
70
+
71
+ The team journal repository is: <paste repository URL>
72
+ I only need to recall and research existing decisions. Do not publish, share,
73
+ sync, push, or create journal entries unless I explicitly ask later.
74
+
75
+ Please:
76
+ 1. Verify Node.js and npm are available.
77
+ 2. Install or update djournal with `npm install -g djournal`.
78
+ 3. Clone the team journal repository if it is not already cloned.
79
+ 4. Run `djournal install --instructions-only` in the cloned journal repository.
80
+ 5. Configure standalone pull access with:
81
+ - `djournal config sync.enabled true`
82
+ - `djournal config sync.mode standalone`
83
+ - `djournal config sync.path .`
84
+ - `djournal config sync.auto false`
85
+ 6. Run `djournal pull` and `djournal status`.
86
+ 7. Report whether recall is ready and show the active work item if one exists.
87
+
88
+ Keep this setup read-only for the organization remote. If a command would write
89
+ to the remote, stop and explain why.
90
+ ```
91
+
92
+ ## Reader Prompts
93
+
94
+ Good prompts for read-only users:
95
+
96
+ ```text
97
+ Recall why we chose the current billing webhook retry strategy.
98
+ ```
99
+
100
+ ```text
101
+ Find product decisions about onboarding and summarize the evidence.
102
+ ```
103
+
104
+ ```text
105
+ Research the journal history for risks in changing the checkout flow. Do not
106
+ edit files or write a journal entry.
107
+ ```
108
+
109
+ ```text
110
+ Show the timeline for the mobile launch work item and list unresolved decisions.
111
+ ```
112
+
113
+ Avoid prompts that imply write behavior unless the user really intends to
114
+ contribute:
115
+
116
+ - "Implement this"
117
+ - "Record a decision"
118
+ - "Share this work"
119
+ - "Sync my journal"
120
+
121
+ ## Organization Admin Checklist
122
+
123
+ For a reader-friendly remote:
124
+
125
+ - Put shared journal projection content in a standalone Git repository.
126
+ - Grant readers clone/pull access only.
127
+ - Keep sensitive or local-only work out of the shared projection.
128
+ - Publish only reviewed work items with `djournal share` and `djournal sync`
129
+ from a maintainer machine or CI account.
130
+ - Provide the repository URL and the copy/paste setup prompt above.
131
+
132
+ ## Product Gaps
133
+
134
+ The current workflow is usable but too manual for non-technical people. A better
135
+ first-class experience would add:
136
+
137
+ - `djournal connect <repo-url> --read-only`, which clones or opens the remote,
138
+ installs instructions, configures standalone pull, disables auto-sync, and
139
+ runs status.
140
+ - `djournal recall-ready`, or an expanded `status`, that explains in plain
141
+ language whether the local reader can use recall.
142
+ - A config flag such as `sync.readOnly: true` that causes `share` and `sync` to
143
+ fail before attempting Git publication.
144
+ - Documentation or generated prompts tailored per harness.
145
+
146
+ ## Related docs
147
+
148
+ - [Installation and repository layouts](installation.md)
149
+ - [Remote Git sync setup](remote-sync.md)
150
+ - [Visibility and sharing](visibility-and-sharing.md)
@@ -6,10 +6,11 @@ transport they use for code. There are two different modes:
6
6
  - colocated `.journal/` in a product repository
7
7
  - standalone journal repository for multi-repo or team-wide memory
8
8
 
9
- The `djournal sync` command is opt-in and intended for standalone journal
10
- repositories or colocated projections. The canonical journal stays in
11
- `~/.djournal/projects/<project-key>/`; sync copies explicitly shared work into
12
- the configured Git-backed projection.
9
+ The `djournal pull` and `djournal sync` commands are opt-in and intended for
10
+ standalone journal repositories or colocated projections. The canonical journal
11
+ stays in `~/.djournal/projects/<project-key>/`. Pull hydrates that store from
12
+ the projection; sync pulls first and then copies explicitly shared work back
13
+ into the projection for publication.
13
14
 
14
15
  ## Colocated repository
15
16
 
@@ -102,7 +103,19 @@ from the sharing index does not remove it from Git history or teammates' clones.
102
103
 
103
104
  ## Synchronizing shared work
104
105
 
105
- Run sync manually:
106
+ Pull every projected work item into canonical storage:
107
+
108
+ ```bash
109
+ djournal pull
110
+ ```
111
+
112
+ Or pull one work item:
113
+
114
+ ```bash
115
+ djournal pull --work 2026-07-03-01-git-backed-journal-collaboration
116
+ ```
117
+
118
+ Publish shared work:
106
119
 
107
120
  ```bash
108
121
  djournal sync
@@ -116,11 +129,15 @@ djournal sync --work 2026-07-03-01-git-backed-journal-collaboration
116
129
 
117
130
  Current behavior:
118
131
 
119
- - sync is skipped unless global `config.json` opts in
120
- - unshared work is skipped
121
- - colocated mode copies shared work into the configured product repo projection
122
- - standalone mode copies shared work and then uses conservative Git operations
123
- - unresolved journal conflicts stop sync
132
+ - pull and sync are skipped unless global `config.json` opts in
133
+ - standalone pull runs `git pull --ff-only` before canonical hydration
134
+ - colocated pull hydrates from the current checkout but never pulls the product
135
+ repository itself
136
+ - pull uses the prior synchronized projection as a three-way baseline
137
+ - one-sided edits and non-overlapping text changes merge automatically
138
+ - overlapping edits and remote deletions stop without changing canonical files
139
+ - sync pulls first, skips unshared publication, then projects and pushes
140
+ - Git staging and conflict checks are scoped to `.journal/work`
124
141
 
125
142
  Hook-triggered sync uses the same command path with `--auto` only when
126
143
  global config enables standalone automatic sync and the closed work is shared.
@@ -128,6 +145,26 @@ The hook derives the work item from the validated closed marker path, so a
128
145
  response that closes `.journal/work/<slug>/journal/...` synchronizes that
129
146
  `<slug>` even if `state.json` currently selects a different active work item.
130
147
 
148
+ Configured standalone automatic sync also pulls when a new chat/session starts.
149
+ The `init-work` and `switch` workflows pull before enumerating work, and an
150
+ explicit request such as “sync the journal” triggers a pull before the agent
151
+ handles publication. Automatic hook failures are reported as bounded context;
152
+ explicit pull/sync conflicts exit nonzero for manual resolution.
153
+
154
+ ## Conflict behavior
155
+
156
+ Pull compares three versions of every durable work file:
157
+
158
+ - the last successfully observed projection baseline
159
+ - the canonical local file
160
+ - the current projected remote file
161
+
162
+ If only one side changed, that side is preserved. Non-overlapping concurrent
163
+ text edits are merged. If the same lines changed incompatibly, or the remote
164
+ deleted durable history, pull returns the conflicting logical paths and does not
165
+ apply any canonical changes or advance the baseline. Resolve those files in the
166
+ projection or canonical store, then rerun `djournal pull`.
167
+
131
168
  ## Keep local state local
132
169
 
133
170
  Do not use Git as a blind mirror of every operational file. Treat these as
@@ -135,6 +172,7 @@ local operational state unless a future workflow explicitly says otherwise:
135
172
 
136
173
  - `.journal/state.json`
137
174
  - `.journal/.install/`
175
+ - the canonical store's `.sync/` reconciliation baseline
138
176
  - `.djournal.json` when the team does not want to share the local store pointer
139
177
  - local harness cache or runtime files
140
178
 
@@ -143,5 +181,6 @@ The durable team memory is the work item content: `work.md`, `journal/`,
143
181
 
144
182
  ## Related docs
145
183
 
184
+ - [Read-only team journal access](read-only-team-journal.md)
146
185
  - [Visibility and sharing](visibility-and-sharing.md)
147
186
  - [Architecture and data model](architecture.md)
@@ -51,7 +51,13 @@ or push for the configured mode.
51
51
 
52
52
  ## Sync and visibility
53
53
 
54
- Run sync:
54
+ Hydrate canonical storage from the shared projection:
55
+
56
+ ```bash
57
+ djournal pull
58
+ ```
59
+
60
+ Then publish shared local work:
55
61
 
56
62
  ```bash
57
63
  djournal sync
@@ -75,9 +81,11 @@ djournal config sync.mode colocated
75
81
  djournal sync
76
82
  ```
77
83
 
78
- In colocated mode, sync copies shared work into the product repository
79
- projection. In standalone mode, sync copies shared work into the standalone
80
- journal repository and performs conservative Git operations.
84
+ In colocated mode, pull reads the current product repository projection without
85
+ performing product Git operations. In standalone mode, pull fast-forwards the
86
+ journal repository before hydrating canonical storage. Sync always pulls first;
87
+ it then copies shared work into the projection and, in standalone mode, commits
88
+ and pushes it.
81
89
 
82
90
  ## Safety model
83
91