# Human usability goal

> Historical journal: this captures the earlier human-usability baseline. The current command surface is documented in [CLI reference](cli-reference.md).

This journal tracks the stage objective: make the existing Reliora MVP understandable and usable by a first-time human without source-code knowledge or author assistance. Scores measure that experience, not feature breadth. The score will never be set to 100; real-user feedback is still required.

## Initial audit

Date: 2026-07-11

Initial human-usability score: **56/100**

### Main problems

- The README Quick Start began with a source checkout and later required an absolute path into that checkout. It was not a linear installed-package journey.
- A user had to infer the full input JSON schema; no `reliora template` command or packaged template existed.
- `reliora init` printed only a path. It did not explain the created workspace, the absence of automatic agent integration, or the next useful command.
- Root and command help omitted the first-use order; command help had no examples and no template command.
- Typical human errors were technically correct but terse (`Invalid number of positional arguments`) and did not consistently suggest a recovery step.
- The README showed a TypeScript-shaped JSON example but did not explain field meanings, requiredness, or distinctions such as solution versus why-it-worked and project context versus applicability.
- The manual workflow with a coding agent and the current lack of automatic integration were not presented as a copyable operating procedure.
- The tarball smoke test exercised a packaged fixture rather than proving that a new user could generate, save, and record a valid template.

### Existing strengths

- The core local init, record, search, show, and feedback cycle worked.
- Human and versioned JSON output already existed.
- Runtime validation, local storage, search ranking, corruption isolation, and secret checks had technical test coverage.
- An installed-tarball smoke test and a project-specific PostgreSQL demo already existed.

## Iteration 1: close the first-run gaps

Date: 2026-07-11

### Changes completed

- Added `reliora template` and `reliora template --json`, backed by a typed valid draft.
- Added `examples/experience-template.json` and a test that keeps it structurally identical to CLI output.
- Changed human `init` output to state what was created, what was not automated, and the next three steps. The existing JSON success shape remains separate.
- Added the complete `init -> template -> record -> search -> show -> feedback` order to root help.
- Added concise purpose, syntax, and at least one executable example to every key command's help.
- Added human-only remediation text for pre-init use, missing input/file, invalid/incomplete JSON, empty search, unknown ID, conflicting feedback flags, and unknown options. JSON error envelopes retain their version, command, code, and message shape.
- Fixed the stdin positional sentinel `-`, which strict option parsing had incorrectly rejected.
- Rebuilt the README around an installed-package five-minute Quick Start, honest init semantics, typical workflow, a reproducible PostgreSQL scenario, field-by-field model documentation, a copyable coding-agent prompt, platform notes, and bounded MVP scope.
- Expanded the installed-tarball smoke test to generate the template, redirect it to a project file, record it, verify all help pages, check raw and enveloped template output, and assert a guiding error.
- Expanded integration coverage for the complete error and discoverability matrix.

### Evidence so far

| Command | Result |
|---|---|
| `npm.cmd run build` | Passed |
| `npm.cmd run lint` | Passed |
| `npm.cmd test` | Passed, 21/21 tests before the final error-matrix expansion |
| `npm.cmd run demo` | Passed; project context selected the specific PostgreSQL lesson over the generic record |
| `npm.cmd run test:package` | Passed; 9 required files and the installed template-based CLI cycle |

### Verification commands still required for completion

- clean `npm.cmd ci`
- build, typecheck, lint, and the expanded unit/integration suite
- demo and installed-package smoke test
- `npm.cmd pack --dry-run`
- `npm.cmd audit --audit-level=high`
- a manual README-only Quick Start in a clean temporary directory using the installed tarball

### Remaining risks

- The final verification matrix has not yet been rerun after the last error-path change.
- The five-minute claim has not yet been timed through the final README text.
- Windows is the only locally available operating system; Linux behavior is covered by platform-neutral Node code and CI configuration but not a live local shell in this iteration.
- Package publication/name availability is a release concern. The documented tarball alternative provides the same install-and-use journey without a source checkout.

Score after iteration 1: **88/100**

The product surface is now understandable, but a score above 90 is withheld until every required gate and the manual installed-tarball journey pass from clean state.

## Iteration 2: verify the literal README journey

Date: 2026-07-11

### Problem found

The first manual run from a globally installed tarball failed at `reliora record experience.json` on Windows PowerShell 5.1. Its `>` redirection wrote BOM-marked UTF-16 JSON, while the CLI input reader assumed UTF-8. This was a genuine first-user blocker hidden by source and package tests that passed UTF-8 fixtures directly.

### Change completed

The CLI input boundary now accepts UTF-8 with or without a BOM and BOM-marked UTF-16 little- or big-endian JSON. No domain, storage, ranking, or JSON output contract changed. A regression test records the real UTF-16 form produced by Windows PowerShell redirection, and the README states the verified platform behavior.

### Final verification evidence

| Check | Result |
|---|---|
| Clean install: `npm.cmd ci` | Passed; 110 packages installed from the lockfile |
| Build: `npm.cmd run build` | Passed |
| Typecheck: `npm.cmd run typecheck` | Passed |
| Lint: `npm.cmd run lint` | Passed |
| Unit/integration: `npm.cmd test` | Passed; 21/21 tests |
| Demo: `npm.cmd run demo` | Passed; the specific PostgreSQL lesson beat a generic competitor with project context |
| Installed artifact: `npm.cmd run test:package` | Passed; 9 required files plus help, init, template, record, search, show, feedback, human/JSON output, and a guiding error |
| Package contents: `npm.cmd pack --dry-run` | Passed; 47 files, 27.2 kB packed / 102.9 kB unpacked |
| Dependency audit: `npm.cmd audit --audit-level=high` | Passed; 0 vulnerabilities |
| Manual README-only Quick Start | Passed from a global `reliora-0.1.0.tgz` install in a clean temporary project on Windows PowerShell 5.1 |

The manual run used the README sequence: `init`, redirected `template`, `record`, human `search`, ID extraction equivalent to copying the printed UUID, `show`, and `feedback --success`. The final JSON `show` confirmed that one successful reuse was persisted. The project had no access to the Reliora source checkout.

### Package evidence

The tarball contains `README.md`, `LICENSE`, `package.json`, the built CLI and public API with declarations/source maps, `examples/experience-template.json`, both demo experience fixtures, and `scripts/demo.mjs`. Development tests and source files are intentionally excluded.

### Final repeat audit

The first-use path no longer requires schema guessing, developer paths, or source checkout access. `init` states its limited semantics and next action. The template is directly recordable. Search prints the ID needed by `show` and `feedback`. Help teaches the order and examples. Common errors point to recovery. The README distinguishes manual use from nonexistent automation and explains each user-authored field.

Final human-usability score: **94/100**

### Remaining limitations

- The published package command cannot be proven until a human performs the external npm release; the identical tarball install path is proven locally.
- Search remains lexical and can miss synonyms or typos.
- Secret detection is best effort, and concurrent feedback updates are not coordinated.
- Linux/macOS behavior is covered by platform-neutral code, installed-package tests, and the CI matrix, but this final manual run was on the available Windows host.
- Real unfamiliar-user observation may still reveal terminology or pacing issues; this is why the score is not 100.

### Readiness and next roadmap stage

Stage 1 is ready: a new user can install the artifact, understand the model, and complete the first useful manual cycle from the README. The next stage should be a small observed usability evaluation with unfamiliar users, followed by evidence-driven wording and workflow refinements. MCP, automatic coding-agent hooks, LLM APIs, embeddings, cloud sync, and other architectural expansion remain out of scope until that evidence exists.