Skip to content

give the front page one install path and put the problem before it - #59

Merged
hyj28 merged 1 commit into
mainfrom
readme-front-door
Sep 24, 2026
Merged

hyj28 merged 1 commit into
mainfrom
readme-front-door

Conversation

@hyj28

@hyj28 hyj28 commented Sep 24, 2026

Copy link
Copy Markdown
Owner

The repository page reads as finished, so this is about the four places it still misleads a first-time reader rather than about what is missing.

The problem statement sat inside ## Quick start. Two paragraphs of motivation — the four-hour task cliff, context rot versus goal drift — were rendered as if they were a step of the installation, and a reader got uv sync before they got a reason to care. They now have their own section, above the install.

Two install blocks disagreed. Quick start said uv sync --extra dev; a later "Development setup" said uv venv && uv pip install -e ".[dev]". Neither was wrong, which is worse than one being wrong — a newcomer has to guess which one this project actually means. One block remains, carrying the facts the second existed to state.

The component table repeated "done" seventeen times. A column whose every cell is identical is not a status, and it displaced the fact a reader needs: which of these switch anything. It is now the loop in prose, plus a table of the flags.

Checking those flag names against harbor_native_agent.py found two of them do not exist. Retrieval is driftlock_agentic_retrieval, not driftlock_retrieval. Compaction has no boolean at all — it is always on, bounded by driftlock_max_history_characters, so listing it as opt-in was wrong in both directions. MCP's absence from the harness is now stated with its reason, rather than reading as an omission.

Dropped the stars badge. A star count is a live claim about traction; putting one on the page makes the page argue about the wrong thing, and this page's argument is the measurement.

Gates

Documentation only — no source or test file is touched, so the suite is unchanged at 1277 passed, 3 skipped and Gate 4 does not apply. Every local link in *.md and docs/*.md resolves, checked by walking the link targets.

The motivation paragraphs sat inside `## Quick start` with no heading of their own,
so the page told a reader how to install before telling them what the problem was,
and then explained the problem as if it were a step of the installation.

Two install blocks disagreed: `uv sync --extra dev` under Quick start and
`uv venv && uv pip install -e ".[dev]"` under Development setup. One canonical
block now carries the facts the second one existed to state.

The component table spent seventeen rows repeating the word "done". Replaced with
the loop in prose and a table of the flags that actually switch something — which
required checking them against `harbor_native_agent`, where two of the names I had
written down do not exist: retrieval is `driftlock_agentic_retrieval`, and
compaction has no boolean at all (it is always on, bounded by
`driftlock_max_history_characters`). MCP's absence from the harness is stated with
its reason rather than left looking like an oversight.

Dropped the stars badge. A star count is a live claim about traction, and putting
it on the page makes the page argue about the wrong thing.
@hyj28
hyj28 merged commit a677f79 into main Sep 24, 2026
2 checks passed
@hyj28
hyj28 deleted the readme-front-door branch September 24, 2026 07:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant