P3-10b: User documentation and administrator deployment guide #43

New issue

Open

opened 2026-09-10 17:57:49 +00:00 by Cordy · 1 comment

Cordy commented

2026-09-10 17:57:49 +00:00

Owner

Depends on P3-10. Do this before P3-11 (release gate) — an unreleased client with no documentation cannot be beta-tested by anyone outside this repo.

Written by whoever writes the code. Documentation drifts from reality the moment it is written by someone who did not build the thing. If you implemented the MSI properties, you write the section on them.

Files

Create: docs/user-guide.md, docs/admin-deployment.md, docs/troubleshooting.md
Modify: README.md

1. User guide

For someone who has never heard of WebDAV and does not want to.

Install, per platform. What the first-run wizard asks for and why.
What sync actually does, in plain terms: this folder and your Cairn stay the same; changes go both ways.
What a conflict is and what to do — both versions are kept, you choose which keeps the original name. Show the conflict filename format so people recognise it in their file manager.
Why a file was skipped — the reasons the engine produces (illegal filename on Windows, case collision, quota full, file in use), each with the fix.
Pausing, changing folders, signing out.
How to export diagnostics and where to send them.

Write for the person who is annoyed. Every page here is read by someone whose files did not do what they expected.

2. Administrator deployment guide

This is the document that makes an organisation adopt you, and the one competitors charge for.

Silent install with the full msiexec property list from P3-9. Every public property, with an example. An admin should never need to read the .wxs.
GPO deployment using the ADMX/ADML template: where to put the files, which settings appear, what each does.
Intune / SCCM assignment.
The complete policy key list from P3-1 with types, defaults, and platform-specific locations (Windows registry path, macOS preference domain, Linux /etc/cairn/policy.json).
Zero-touch enrolment — the cairn:// URL format and QR code.
Branding — the build-time options, and the explicit statement that this is free and ungated.
Network behaviour — the §8.3 statement verbatim: the server never phones home; the client does exactly two optional things (update check, opt-in crash reports), both disableable by policy. An enterprise reviewer looks for exactly this, and its absence reads as evasion.
macOS and Linux equivalents for each of the above.

3. Troubleshooting

Sync is not starting · a file will not sync · sign-in fails on an OIDC server (app password) · "Cairn is full" · watch-limit exhaustion on Linux (fs.inotify.max_user_watches) · slow first sync on a large tree.
Where logs live per platform.
How to run cairnsync --once --dry-run to see what the engine intends without it doing anything. This is the best debugging tool in the product — say so.

Language

English only. These are reference documents; the UI is translated (P3-3b), the docs are not. Revisit if a customer asks.

Steps

Write the three documents.
Verify every documented MSI property and policy key against the actual implementation — no aspirational documentation.
Have someone who did not build it follow the user guide on a clean machine and complete setup.
Link from README.md.
Commit: git commit -s -m "docs: user guide, admin deployment guide, troubleshooting"

Acceptance criteria

Every public MSI property and policy key is documented and verified to work as written.
A non-technical reader can install, connect and resolve a conflict using only the user guide.
The network-behaviour statement appears verbatim.
Nothing documented is unimplemented, and nothing implemented is undocumented.

Depends on P3-10. **Do this before P3-11 (release gate)** — an unreleased client with no documentation cannot be beta-tested by anyone outside this repo. **Written by whoever writes the code.** Documentation drifts from reality the moment it is written by someone who did not build the thing. If you implemented the MSI properties, you write the section on them. ## Files - Create: `docs/user-guide.md`, `docs/admin-deployment.md`, `docs/troubleshooting.md` - Modify: `README.md` ## 1. User guide For someone who has never heard of WebDAV and does not want to. - Install, per platform. What the first-run wizard asks for and why. - **What sync actually does**, in plain terms: this folder and your Cairn stay the same; changes go both ways. - **What a conflict is and what to do** — both versions are kept, you choose which keeps the original name. Show the conflict filename format so people recognise it in their file manager. - **Why a file was skipped** — the reasons the engine produces (illegal filename on Windows, case collision, quota full, file in use), each with the fix. - Pausing, changing folders, signing out. - How to export diagnostics and where to send them. Write for the person who is annoyed. Every page here is read by someone whose files did not do what they expected. ## 2. Administrator deployment guide This is the document that makes an organisation adopt you, and the one competitors charge for. - **Silent install** with the full `msiexec` property list from P3-9. Every public property, with an example. An admin should never need to read the `.wxs`. - **GPO deployment** using the ADMX/ADML template: where to put the files, which settings appear, what each does. - **Intune / SCCM** assignment. - **The complete policy key list** from P3-1 with types, defaults, and platform-specific locations (Windows registry path, macOS preference domain, Linux `/etc/cairn/policy.json`). - **Zero-touch enrolment** — the `cairn://` URL format and QR code. - **Branding** — the build-time options, and the explicit statement that this is free and ungated. - **Network behaviour** — the §8.3 statement verbatim: the server never phones home; the client does exactly two optional things (update check, opt-in crash reports), both disableable by policy. An enterprise reviewer looks for exactly this, and its absence reads as evasion. - macOS and Linux equivalents for each of the above. ## 3. Troubleshooting - Sync is not starting · a file will not sync · sign-in fails on an OIDC server (app password) · "Cairn is full" · watch-limit exhaustion on Linux (`fs.inotify.max_user_watches`) · slow first sync on a large tree. - Where logs live per platform. - How to run `cairnsync --once --dry-run` to see what the engine intends without it doing anything. This is the best debugging tool in the product — say so. ## Language **English only.** These are reference documents; the UI is translated (P3-3b), the docs are not. Revisit if a customer asks. ## Steps - [ ] Write the three documents. - [ ] Verify every documented MSI property and policy key against the actual implementation — no aspirational documentation. - [ ] Have someone who did not build it follow the user guide on a clean machine and complete setup. - [ ] Link from `README.md`. - [ ] Commit: `git commit -s -m "docs: user guide, admin deployment guide, troubleshooting"` ## Acceptance criteria - Every public MSI property and policy key is documented and verified to work as written. - A non-technical reader can install, connect and resolve a conflict using only the user guide. - The network-behaviour statement appears verbatim. - Nothing documented is unimplemented, and nothing implemented is undocumented.

Cordy added this to the phase-3-desktop-app milestone

2026-09-10 17:57:49 +00:00

Cordy added the

scaffold

label

2026-09-10 17:57:49 +00:00

Cordy referenced this issue

2026-09-10 18:10:49 +00:00

P4-7: Files-on-demand gate — THIS is the v1.0 release #50

Cordy referenced this issue

2026-09-10 18:24:01 +00:00

P4-7: Files-on-demand gate — THIS is the v1.0 release #50

Cordy referenced this issue

2026-09-11 20:54:48 +00:00

P2-9: Integration tests against a live cairnd in CI #29

Cordy commented

2026-09-11 20:58:56 +00:00

Author

Owner

Amendment — 2026-09-11: what the guides must say about cairnsync (phase-2 final review)

Phase 2 shipped cmd/cairnsync. Its package doc (cmd/cairnsync/main.go:1-72) is the source of
truth. Several behaviours an administrator must know are recorded only in phase-2 review files. The
administrator guide and the troubleshooting page must state each of these. Under this issue's rule,
"nothing implemented is undocumented", each is a gap until it is written down.

The server URL is the WebDAV folder to sync, <server>/dav/home/ on a Cairn with per-user
homes (P2-R13). /dav/ itself holds only home and spaces.
Names Windows cannot hold are skipped on every host, deliberately (main.go:47-49,
:315-319). Every device of the account shares one Cairn, and any of them may run Windows. So
a:b.txt, CON.txt and a trailing dot or space are skipped with a reason, even on Linux.
Other skipped names: names containing %, which cairnd decodes twice (P2-R15); Cairn's own
.cairn-meta.json, .cairn-state and .cairn-upload-*; symbolic links and other special
entries, together with everything below them; and case collisions.
The state database: there is one per folder pair, and it must lie outside localPath. The
check is lexical, so a spelling that differs in case or goes through a symlink slips past it
(Task 28 F4). Never share a state database between folder pairs, and never copy one to another.
Never run two cairnsync processes on one config. For cron, use loop mode, or wrap each run in
flock (Task 28 F5).
Signals: in --once mode, the first SIGINT or SIGTERM lets the running pass finish, and a
second one stops the process at once (Task 28 F6, CV7). An interrupted upload resumes on the next
run.
Quota: a 507 is a per-file skip whose reason names the quota. It is tried once a pass and
never retried in a loop.
Concurrent edits on cairnd bd006ef: cairnd ignores If-Match and If-None-Match (P2-R16). Two
clients writing one file at the same moment can overwrite each other. The client re-checks each
copy just before writing, which narrows that window but cannot close it.
Mount the sync folder first. If the folder is on a disk or network share that is not mounted,
the empty mount point reads as every file deleted. Final review X2 adds a refusal for this case.
Document its message, and how an administrator confirms a deliberate delete-all.
Exit codes 0, 1, 2 and 3, and the --json events (main.go:51-71).
Any command in these guides that talks to a server with curl passes the credentials on stdin
(curl -K -), never with -u on the command line (Task 28 F7).

## Amendment — 2026-09-11: what the guides must say about cairnsync (phase-2 final review) Phase 2 shipped `cmd/cairnsync`. Its package doc (`cmd/cairnsync/main.go:1-72`) is the source of truth. Several behaviours an administrator must know are recorded only in phase-2 review files. The administrator guide and the troubleshooting page must state each of these. Under this issue's rule, "nothing implemented is undocumented", each is a gap until it is written down. - **The server URL is the WebDAV folder to sync**, `<server>/dav/home/` on a Cairn with per-user homes (P2-R13). `/dav/` itself holds only `home` and `spaces`. - **Names Windows cannot hold are skipped on every host, deliberately** (`main.go:47-49`, `:315-319`). Every device of the account shares one Cairn, and any of them may run Windows. So `a:b.txt`, `CON.txt` and a trailing dot or space are skipped with a reason, even on Linux. - **Other skipped names:** names containing `%`, which cairnd decodes twice (P2-R15); Cairn's own `.cairn-meta.json`, `.cairn-state` and `.cairn-upload-*`; symbolic links and other special entries, together with everything below them; and case collisions. - **The state database:** there is one per folder pair, and it must lie outside `localPath`. The check is lexical, so a spelling that differs in case or goes through a symlink slips past it (Task 28 F4). Never share a state database between folder pairs, and never copy one to another. - **Never run two cairnsync processes on one config.** For cron, use loop mode, or wrap each run in `flock` (Task 28 F5). - **Signals:** in `--once` mode, the first SIGINT or SIGTERM lets the running pass finish, and a second one stops the process at once (Task 28 F6, CV7). An interrupted upload resumes on the next run. - **Quota:** a 507 is a per-file skip whose reason names the quota. It is tried once a pass and never retried in a loop. - **Concurrent edits on cairnd bd006ef:** cairnd ignores If-Match and If-None-Match (P2-R16). Two clients writing one file at the same moment can overwrite each other. The client re-checks each copy just before writing, which narrows that window but cannot close it. - **Mount the sync folder first.** If the folder is on a disk or network share that is not mounted, the empty mount point reads as every file deleted. Final review X2 adds a refusal for this case. Document its message, and how an administrator confirms a deliberate delete-all. - **Exit codes** 0, 1, 2 and 3, and the `--json` events (`main.go:51-71`). - Any command in these guides that talks to a server with curl passes the credentials on stdin (`curl -K -`), never with `-u` on the command line (Task 28 F7).