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.
- package/.agents/adapters/contract.md +4 -3
- package/.agents/adapters/shared/journal-hook.js +81 -6
- package/.agents/skills/init-work/SKILL.md +12 -9
- package/.agents/skills/switch/SKILL.md +11 -8
- package/.claude/settings.json +3 -3
- package/.codex/hooks.json +3 -3
- package/README.md +14 -4
- package/bin/journal.js +55 -2
- package/docs/architecture.md +10 -3
- package/docs/djournal-in-practice.md +14 -0
- package/docs/installation.md +51 -6
- package/docs/read-only-team-journal.md +150 -0
- package/docs/remote-sync.md +49 -10
- package/docs/visibility-and-sharing.md +12 -4
- package/lib/installer/index.js +353 -10
- package/lib/update-checker.js +177 -0
- package/package.json +5 -2
|
@@ -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)
|
package/docs/remote-sync.md
CHANGED
|
@@ -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`
|
|
10
|
-
repositories or colocated projections. The canonical journal
|
|
11
|
-
`~/.djournal/projects/<project-key
|
|
12
|
-
the
|
|
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
|
-
|
|
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
|
|
120
|
-
-
|
|
121
|
-
- colocated
|
|
122
|
-
|
|
123
|
-
-
|
|
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
|
-
|
|
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,
|
|
79
|
-
|
|
80
|
-
journal repository
|
|
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
|
|