The portal, reviewed from four chairs¶
The directive asks whether four readers can answer their questions from this documentation. The honest test is not whether a page mentions a topic, but whether the reader can get from the question to an answer without leaving the site. Each section below names the questions, the pages that answer them, and what the review changed.
Developer: can I build my first JDLib application?¶
| Question | Where the answer is |
|---|---|
| How do I install it, and what do I need running? | Install, Quickstart |
| How do I configure the database and the tenant? | Configuration, CLI reference |
| How do I scope a query to the tenant? | Tenancy, Resource management |
| How do I add an endpoint, a permission, or a table? | the guides |
| How do I test it without a database? | Testing, Test kit |
| What does a failure look like? | Error codes, Troubleshooting |
What this review changed. The guides and the quickstart were written after this question was
asked, and every command in them is checked against the repository by
tests/unit/test_example_docs.py, which fails when a page documents a command the repository cannot
run.
Architect: can I understand the complete architecture?¶
| Question | Where the answer is |
|---|---|
| What are the pieces, and how do they fit? | High-level architecture, Component architecture |
| Where does tenant data live, and what is derived? | Data architecture |
| What happens to one request, start to finish? | Request lifecycle |
| Why is it built this way, and what was rejected? | Architecture decisions, long-form reference |
| What does a real deployment look like? | Example architecture, Deployment |
What this review changed. The component view had no diagram of the deployment topology - only prose about it. Deployment now draws it, and the MCP page draws the invocation chain it describes.
Security engineer: can I understand the boundaries and the controls?¶
| Question | Where the answer is |
|---|---|
| Where does the tenant come from, and what is refused? | Security architecture, Tenancy |
| What does authorization decide, and on what? | Authorization, Security model |
| What is written down, and what is never written down? | Audit, Observability |
| What happens when a dependency is degraded? | Failure modes |
| How is any of this proven? | Security review, threat model, the review's citations |
What this review changed. The reliability section's failure-mode table said what happens when a dependency is down, but not what a degraded policy engine means. It does now: a degraded decision is a refusal, and the page says so where a reader looking for a retry would find it.
Operations engineer: can I deploy, monitor, troubleshoot, and recover?¶
| Question | Where the answer is |
|---|---|
| In what order do I bring it up? | Deployment |
| How do I know it is ready, and not merely up? | Health and readiness |
| What do I watch, and what does a bad value mean? | Metrics, Failure modes |
| Something is broken - what now? | Troubleshooting, Incident response |
| Is this deployment complete? | Production checklist |
| How do I ship the next revision without dropping requests? | Shutdown and draining |
What this review changed. The troubleshooting page is a symptom table, and every row names the evidence that distinguishes it - because "check the logs" is not a runbook. The production checklist names, for each line, the artifact or command that answers it.
Where the review found a gap and left it visible¶
The documentation test matrix earns its ticks from the tree, and one
cell is honestly empty: no test file names jdlib.observability. The signals are covered through
jdlib.security.telemetry and jdlib.security.tracing, which do have tests. The matrix prints the
gap and the explanation rather than a tick, which is the point of generating it.