The quickstart produces a running server and then abandons the reader
Reading README.md as an outsider, three gaps stop a developer in the first ten minutes. All are cheap.
1. There is no first request
The quickstart runs docker run, explains the three load-bearing env vars, and then jumps to cistern pod create --root /firms/acme/ — a multi-tenant concept with a fictional law firm. There is no moment where the reader stores something and reads it back, which is the moment a developer decides the software works.
Add a PUT and a GET with the owner token, immediately after the run command, before any mention of pods or grants.
2. Nothing explains the owner WebID — and it needs less explanation than it appears to
CISTERN_OWNER_WEBID is the first required variable, and no document in the repo explains what a WebID is or where to get one (grepped README, all of docs/, and the integration kit: zero hits for a primer). Cistern has no Solid-OIDC provider, so it cannot mint one either. Step 1 reads as undefined.
But nothing dereferences the owner WebID. There is no WebID-deref machinery in main source; PodSpec validates only that it is an absolute URI and PodProvisioner writes it into the ACL as an opaque IRI. The https://you.example/profile/card#me placeholder works exactly as written — verified by running it.
So the fix is one sentence saying it is an identifier the server never fetches, and that any absolute URI you control works for evaluation. That turns an apparent cliff into a non-issue, without waiting for Phase 4.
3. The flagship feature is missing from the quickstart
README.md line 4 calls MCP "the flagship interface". The Quickstart never mentions connecting an agent, and docs/demo/claude-desktop.md is not linked from the README. (See #133 for the separate problem that the MCP docs point at target/ jars rather than the published bridge jar.)
Suggested shape
Run it → store and read something back → grant an agent → revoke, and watch the next call be refused. The refusal is the differentiator and it is currently buried in a 66 KB reference document.
DoD
- A reader gets data into and out of the pod without leaving the README.
- The WebID sentence is present.
- An MCP quickstart exists, or the README links to one.
- Meets the existing T7.3 DoD: a stranger goes zero → running pod in 5 minutes.
Related
#43 (T7.3 README + site — this is the concrete content list for it), #133 (doc drift), #39 (flagship demo).
The quickstart produces a running server and then abandons the reader
Reading
README.mdas an outsider, three gaps stop a developer in the first ten minutes. All are cheap.1. There is no first request
The quickstart runs
docker run, explains the three load-bearing env vars, and then jumps tocistern pod create --root /firms/acme/— a multi-tenant concept with a fictional law firm. There is no moment where the reader stores something and reads it back, which is the moment a developer decides the software works.Add a PUT and a GET with the owner token, immediately after the run command, before any mention of pods or grants.
2. Nothing explains the owner WebID — and it needs less explanation than it appears to
CISTERN_OWNER_WEBIDis the first required variable, and no document in the repo explains what a WebID is or where to get one (grepped README, all ofdocs/, and the integration kit: zero hits for a primer). Cistern has no Solid-OIDC provider, so it cannot mint one either. Step 1 reads as undefined.But nothing dereferences the owner WebID. There is no WebID-deref machinery in main source;
PodSpecvalidates only that it is an absolute URI andPodProvisionerwrites it into the ACL as an opaque IRI. Thehttps://you.example/profile/card#meplaceholder works exactly as written — verified by running it.So the fix is one sentence saying it is an identifier the server never fetches, and that any absolute URI you control works for evaluation. That turns an apparent cliff into a non-issue, without waiting for Phase 4.
3. The flagship feature is missing from the quickstart
README.mdline 4 calls MCP "the flagship interface". The Quickstart never mentions connecting an agent, anddocs/demo/claude-desktop.mdis not linked from the README. (See #133 for the separate problem that the MCP docs point attarget/jars rather than the published bridge jar.)Suggested shape
Run it → store and read something back → grant an agent → revoke, and watch the next call be refused. The refusal is the differentiator and it is currently buried in a 66 KB reference document.
DoD
Related
#43 (T7.3 README + site — this is the concrete content list for it), #133 (doc drift), #39 (flagship demo).