id: pm-1sb2
title: Rewrite README and public documentation
description: Shorten README and overhaul public docs with detailed progressive-disclosure guidance for users and agents while excluding private operations material.
type: Task
status: closed
priority: 1
tags[4]: agent-docs,docs,readme,security
created_at: "2026-05-01T20:47:21.143Z"
updated_at: "2026-05-01T21:23:36.593Z"
deadline: "2026-05-02T20:47:21.143Z"
author: codex-agent
estimated_minutes: 150
acceptance_criteria: "README is concise and routes to deeper docs; docs use GitHub-compatible relative links; agent-facing sections are token-efficient with progressive disclosure; public docs reference pm-3042, pm-r9gu, and this task where relevant; private operations material stays local-only and gitignored; links and build verification pass."
parent: pm-r9gu
resolution: "README and public documentation were restructured into a concise entry point plus focused progressive-disclosure docs for users, agents, commands, configuration, testing, architecture, SDK, extensions, and releasing."
expected_result: "Public docs are concise, navigable with GitHub-compatible links, linked to pm tracker items, and exclude private operations material."
actual_result: README is 104 lines; docs index and focused pages were added; changed docs are linked to pm-1sb2; public docs private-string scan passed; package dry-run excludes private operations artifacts; linked coverage passed at 100%.
comments[2]{created_at,author,text}:
  "2026-05-01T21:23:36.581Z",codex-agent,"Duplicate check evidence: ran pm context --limit 10,pm search for README documentation docs progressive disclosure agents private operations,pm list-open --limit 20,and pm list-in-progress --limit 20. No active task covered this README and docs overhaul; closed historical hits were not reusable,so this child task was net-new under pm-r9gu."
  "2026-05-01T21:23:36.581Z",codex-agent,"Evidence: pnpm build passed; markdown link checker passed for 16 public markdown files; public-doc private-string scan passed; local private operations paths are ignored; npm pack dry-run checked 472 files with no private operations artifacts; pnpm security:scan found no credential-like secrets; pm docs/files --validate-paths passed; focused release-readiness and vector-store specs passed; linked coverage passed with 81 files,1088 tests,and 100% coverage. pm validate history drift is clean; remaining resolution warnings are unrelated pre-existing closed items."
notes[1]{created_at,author,text}:
  "2026-05-01T20:51:21.709Z",codex-agent,Private operations material must stay out of public docs and package output.
files[3]{path,scope,note}:
  .gitignore,project,explicit private operations ignore boundary
  tests/integration/release-readiness-runtime.spec.ts,project,release-readiness assertion drift fixed for documentation verification
  tests/unit/vector-store-adapter.spec.ts,project,coverage guard for LanceDB zero-vector and tie sort branches
tests[1]{command,path,scope,timeout_seconds,pm_context_mode,env_set,env_clear,shared_host_safe,assert_stdout_contains,assert_stdout_regex,assert_stderr_contains,assert_stderr_regex,assert_stdout_min_lines,assert_json_field_equals,assert_json_field_gte,note}:
  node scripts/run-tests.mjs coverage,null,project,900,null,null,null,null,null,null,null,null,null,null,null,sandboxed repository coverage gate
test_runs[3]{run_id,kind,status,started_at,finished_at,recorded_at,attempt,resumed_from,passed,failed,skipped,items,linked_tests,fail_on_skipped_triggered}:
  test-local-monehrg0-ogf7tf,test,failed,"2026-05-01T20:58:05.650Z","2026-05-01T21:04:11.568Z","2026-05-01T21:04:11.568Z",null,null,0,1,0,null,null,null
  test-local-monetrew-rpl4n0,test,failed,"2026-05-01T21:07:11.939Z","2026-05-01T21:13:31.400Z","2026-05-01T21:13:31.400Z",null,null,0,1,0,null,null,null
  test-local-monf267h-gdmbkg,test,passed,"2026-05-01T21:14:35.654Z","2026-05-01T21:20:03.821Z","2026-05-01T21:20:03.821Z",null,null,1,0,0,null,null,null
docs[16]{path,scope,note}:
  CHANGELOG.md,project,documentation change entry
  CONTRIBUTING.md,project,developer doc routing
  docs/AGENT_GUIDE.md,project,public documentation overhaul
  docs/ARCHITECTURE.md,project,public documentation overhaul
  docs/COMMANDS.md,project,public documentation overhaul
  docs/CONFIGURATION.md,project,public documentation overhaul
  docs/examples/starter-extension/README.md,project,public documentation overhaul
  docs/EXTENSIONS.md,project,public documentation overhaul
  docs/QUICKSTART.md,project,public documentation overhaul
  docs/README.md,project,public documentation overhaul
  docs/RELEASING.md,project,public documentation overhaul
  docs/SDK.md,project,public documentation overhaul
  docs/TESTING.md,project,public documentation overhaul
  PRD.md,project,current docs navigation
  README.md,project,short entry point
  SECURITY.md,project,private data handling
close_reason: "README and public documentation overhauled with progressive disclosure, tracker cross-links, private operations exclusion, passing link/package/security/build checks, and linked 100% coverage."
body: "Implementation task for the 2026-05-01 documentation request. Work updated README.md and public docs, added focused progressive-disclosure pages, kept private operations material local-only, and linked changed files plus verification back to this item."