docs: answer-first README opening + anchor doc (why raw exports fail as agent context)

[GiaSip]

Files changed

• docs/why-note-exports-fail-as-agent-context.md (new): the anchor document. Four measured failure modes of pointing an agent at a raw note export (empty shells ~54–61%, missing/lying dates — 5.2%/6.3% parseable creation dates, 0% truthful mtime staleness; link dialects that don't survive flattening; unreviewed compression) → six criteria a compile step must satisfy (drop shells but keep receipts; never emit a live wrong link; honest date fallback with a coverage gate; human gate on archive content; state its own coverage; land in the file the agent reads) → how kb-init implements each → honest limitations.
• README.md: opening line changed to problem-first ("A years-old note export is mostly empty shells — an AI agent can't use it as-is…") + one pointer line to the anchor doc. No forced question phrasing.
• README.zh-CN.md: same opening change + one-line Chinese pointer to the anchor doc (no parallel translation).

Evidence base

• All numbers (1,925→757 / 60.7%, 620→287 / 53.7%, 5.2%/6.3%/43% date rates, ~70% residual, 16–23% coverage, 9-of-10 and 3-of-5 recognizable clusters, 0% mtime staleness, 11–15 nesting levels) come from the existing README.md and docs/DESIGN.md; nothing new is invented. Internal-only DESIGN content (naming deliberations, competitor analysis) is excluded from the public doc.
• Criteria map to documented behavior: manifest ledgers, unresolved_links degradation, time_axis gate at 30%, insights checklist word-for-word compile, coverage section, --agent-file.

Also in this PR (metadata, reversible)

• Repo description updated to answer-first via gh repo edit (done separately as a repo setting, not a file in this branch).

Not in this PR

Homepage change deferred until after merge (it points at the new anchor doc).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67cb0d8ba2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Qualify link degradation in wikilink mode

When users select --wikilinks, unresolved non-ambiguous wikilinks do not degrade to plain text: _convert_links preserves them, and README.md:309-312 explicitly documents that output may contain links to nonexistent files. This unconditional implementation claim therefore gives users of that supported mode a false link-safety guarantee; limit it to the default mode or describe the wikilink exception.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Correct the measurement provenance

Revise this provenance statement because not all subsequent numbers come from the two exports or are reproduced in the README: the 0% mtime result at lines 20-21 was measured on a separate maintained knowledge base, and the 11–15-level nesting result at lines 25-26 is sourced from docs/DESIGN.md rather than the README. As written, the anchor document misstates the evidence base it is intended to make auditable.

Useful? React with 👍 / 👎.