docs: rewrite README as project landing page

ldraney commented

2026-06-13 20:46:36 +00:00

Author

Owner

PR #281 Review

DOMAIN REVIEW

Documentation-only PR. Single file changed: README.md. Tech stack: Markdown documentation for a Python/FastAPI/SQLAlchemy platform.

Metric verification against codebase (all checked against source files on main):

Claim	Verified	Source
48 API Endpoints	CORRECT	48 route decorators across 9 route modules in `src/pal_e_docs/routes/`
45+ MCP Tools	Not verifiable here	MCP server lives in `pal-e-mcp` repo -- reasonable claim given tool surface
709+ Tests	Consistent	Matches PR #279 and CLAUDE.md
11 SQLAlchemy Models	CORRECT	`models.py`: User, Project, Repo, Note, Tag, NoteTag, NoteLink, NoteRevision, Block, CompiledPage, BoardItem
24 Alembic Migrations	CORRECT	24 `.py` files in `alembic/versions/`
2,560 Embedding Dimensions	CORRECT	`Vector(2560)` in `models.py` line 241
8 Kanban Columns	CORRECT	`BoardColumn` enum in `models.py`
14 Note Types	CORRECT	`NoteTypeEnum` in `schemas.py`
6 Board Item Types	CORRECT	`BoardItemType` enum in `models.py`

docs/ links: All 5 documentation links (architecture.md, database.md, api-endpoints.md, embedding-pipeline.md, deployment.md) reference files created in merged PR #279. Links will resolve.

Content quality: The rewrite successfully transforms a developer-reference README into a landing page that explains why the platform exists and how the architecture works. The progression (Why This Exists -> How It Works -> The Stack -> By the Numbers -> Documentation -> Quick Start) is well-structured. Technical deep-dives (embedding pipeline ASCII diagram, RRF table, board column flow) are clear and accurate.

Title change: pal-e-api -> pal-e-docs in the H1. This aligns with the project name convention (project is pal-e-docs, repo was renamed to pal-e-api). Intentional and consistent with CLAUDE.md.

Internal URL removal: The Related Repositories table previously had internal Forgejo URLs (https://forgejo.tail5b443a.ts.net/forgejo_admin/...). The new README replaces these with bold repo names only. Good practice -- avoids leaking internal infrastructure URLs.

BLOCKERS

None.

This is a documentation-only PR with no code changes. All BLOCKER criteria (test coverage, input validation, secrets, auth DRY) are not applicable. No secrets or credentials appear in the diff.

NITS

MCP tool categories table: The table lists 10 + 8 + 10 + 5 + 9 = 42 tools, but the text says "45+ tools." The "45+" claim may be correct if some tools are not listed in the table, but the table subtotals suggest 42. Consider either adjusting the number or adding a note that the table is illustrative, not exhaustive. (Very minor -- "45+" is directionally correct and the + covers it.)
"By the Numbers" section omits route module count: The old README stated "48 across 9 route modules." The new README says just "48" for API Endpoints. The 9-module detail is useful context -- consider restoring it (e.g., "48 (9 modules)") or leaving it to docs/api-endpoints.md which already covers it.
"Boards Are Notes" section: The statement "a board is a note with note_type=\"board\"" is accurate. However, the phrase "When a phase note's status changes, its board item moves automatically" describes behavior that lives in the MCP/agent layer, not in the API itself. Worth verifying whether this auto-move is actually triggered by a database trigger or application code in this repo vs. being an agent-level workflow. If it's agent-level, the README makes it sound like an API feature.

SOP COMPLIANCE

PR body has: Summary, Changes, Test Plan, Related -- all present and well-structured
PR body references parent issue: "Closes #280"
No secrets committed
No unnecessary file changes (single file: README.md)
Commit message is descriptive: "docs: rewrite README as project landing page"
Review Checklist present in PR body

PROCESS OBSERVATIONS

This PR builds on PR #279 (docs restructuring) which created the docs/ directory. The two-step approach (restructure first, then rewrite) is clean and reduces review scope.
The README transformation from developer reference to landing page supports discoverability -- new contributors can understand the system's purpose before diving into technical docs.
All numeric claims were verified against source code. The PR body's Test Plan includes metric verification checkboxes, which is good practice for documentation PRs.

VERDICT: APPROVED

## PR #281 Review ### DOMAIN REVIEW Documentation-only PR. Single file changed: `README.md`. Tech stack: Markdown documentation for a Python/FastAPI/SQLAlchemy platform. **Metric verification against codebase (all checked against source files on main):** | Claim | Verified | Source | |-------|----------|--------| | 48 API Endpoints | CORRECT | 48 route decorators across 9 route modules in `src/pal_e_docs/routes/` | | 45+ MCP Tools | Not verifiable here | MCP server lives in `pal-e-mcp` repo -- reasonable claim given tool surface | | 709+ Tests | Consistent | Matches PR #279 and CLAUDE.md | | 11 SQLAlchemy Models | CORRECT | `models.py`: User, Project, Repo, Note, Tag, NoteTag, NoteLink, NoteRevision, Block, CompiledPage, BoardItem | | 24 Alembic Migrations | CORRECT | 24 `.py` files in `alembic/versions/` | | 2,560 Embedding Dimensions | CORRECT | `Vector(2560)` in `models.py` line 241 | | 8 Kanban Columns | CORRECT | `BoardColumn` enum in `models.py` | | 14 Note Types | CORRECT | `NoteTypeEnum` in `schemas.py` | | 6 Board Item Types | CORRECT | `BoardItemType` enum in `models.py` | **docs/ links**: All 5 documentation links (architecture.md, database.md, api-endpoints.md, embedding-pipeline.md, deployment.md) reference files created in merged PR #279. Links will resolve. **Content quality**: The rewrite successfully transforms a developer-reference README into a landing page that explains _why_ the platform exists and _how_ the architecture works. The progression (Why This Exists -> How It Works -> The Stack -> By the Numbers -> Documentation -> Quick Start) is well-structured. Technical deep-dives (embedding pipeline ASCII diagram, RRF table, board column flow) are clear and accurate. **Title change**: `pal-e-api` -> `pal-e-docs` in the H1. This aligns with the project name convention (project is `pal-e-docs`, repo was renamed to `pal-e-api`). Intentional and consistent with CLAUDE.md. **Internal URL removal**: The Related Repositories table previously had internal Forgejo URLs (`https://forgejo.tail5b443a.ts.net/forgejo_admin/...`). The new README replaces these with bold repo names only. Good practice -- avoids leaking internal infrastructure URLs. ### BLOCKERS None. This is a documentation-only PR with no code changes. All BLOCKER criteria (test coverage, input validation, secrets, auth DRY) are not applicable. No secrets or credentials appear in the diff. ### NITS 1. **MCP tool categories table**: The table lists 10 + 8 + 10 + 5 + 9 = 42 tools, but the text says "45+ tools." The "45+" claim may be correct if some tools are not listed in the table, but the table subtotals suggest 42. Consider either adjusting the number or adding a note that the table is illustrative, not exhaustive. (Very minor -- "45+" is directionally correct and the `+` covers it.) 2. **"By the Numbers" section omits route module count**: The old README stated "48 across 9 route modules." The new README says just "48" for API Endpoints. The 9-module detail is useful context -- consider restoring it (e.g., "48 (9 modules)") or leaving it to docs/api-endpoints.md which already covers it. 3. **"Boards Are Notes" section**: The statement "a board is a note with `note_type=\"board\"`" is accurate. However, the phrase "When a phase note's status changes, its board item moves automatically" describes behavior that lives in the MCP/agent layer, not in the API itself. Worth verifying whether this auto-move is actually triggered by a database trigger or application code in this repo vs. being an agent-level workflow. If it's agent-level, the README makes it sound like an API feature. ### SOP COMPLIANCE - [x] PR body has: Summary, Changes, Test Plan, Related -- all present and well-structured - [x] PR body references parent issue: "Closes #280" - [x] No secrets committed - [x] No unnecessary file changes (single file: README.md) - [x] Commit message is descriptive: "docs: rewrite README as project landing page" - [x] Review Checklist present in PR body ### PROCESS OBSERVATIONS - This PR builds on PR #279 (docs restructuring) which created the docs/ directory. The two-step approach (restructure first, then rewrite) is clean and reduces review scope. - The README transformation from developer reference to landing page supports discoverability -- new contributors can understand the system's purpose before diving into technical docs. - All numeric claims were verified against source code. The PR body's Test Plan includes metric verification checkboxes, which is good practice for documentation PRs. ### VERDICT: APPROVED

2026-06-13 20:44:06 +00:00

Summary

Rewrites README from developer reference into a landing page that sells the unified knowledge platform concept
Leads with the core insight: knowledge, work state, and search collapsed into one Postgres store
All claims verified against actual codebase (models.py, search.py, embedding_worker.py, routes/)

Changes

README.md: Full rewrite — new structure with Why This Exists, How It Works (block-level content, on-write embeddings, hybrid RRF search, boards-as-notes, note graph, MCP-native), The Stack, By the Numbers. Technical deep-dives remain in docs/. Internal Forgejo URLs removed from Related Repos.

Test Plan

README renders correctly on Forgejo
docs/ links resolve
All stated metrics match codebase (48 endpoints, 45+ MCP tools, 709+ tests, 2560-dim embeddings, 14 note types, 8 kanban columns)
No regressions in docs/ content

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive
Feature flag needed? No — documentation only

Closes #280

pal-e-docs — project this work belongs to

## Summary - Rewrites README from developer reference into a landing page that sells the unified knowledge platform concept - Leads with the core insight: knowledge, work state, and search collapsed into one Postgres store - All claims verified against actual codebase (models.py, search.py, embedding_worker.py, routes/) ## Changes - `README.md`: Full rewrite — new structure with Why This Exists, How It Works (block-level content, on-write embeddings, hybrid RRF search, boards-as-notes, note graph, MCP-native), The Stack, By the Numbers. Technical deep-dives remain in docs/. Internal Forgejo URLs removed from Related Repos. ## Test Plan - [ ] README renders correctly on Forgejo - [ ] docs/ links resolve - [ ] All stated metrics match codebase (48 endpoints, 45+ MCP tools, 709+ tests, 2560-dim embeddings, 14 note types, 8 kanban columns) - [ ] No regressions in docs/ content ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive - [ ] Feature flag needed? No — documentation only ## Related Notes Closes #280 - `pal-e-docs` — project this work belongs to

ldraney added 1 commit

docs: rewrite README as landing page for the unified knowledge platform 1e5cd0b255

Restructures README from a developer reference into a selling page that
leads with the core insight — knowledge, work state, and search unified
in one Postgres store — then backs it up with architecture details.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Claim	Verified	Source
48 API Endpoints	CORRECT	48 route decorators across 9 route modules in `src/pal_e_docs/routes/`
45+ MCP Tools	Not verifiable here	MCP server lives in `pal-e-mcp` repo -- reasonable claim given tool surface
709+ Tests	Consistent	Matches PR #279 and CLAUDE.md
11 SQLAlchemy Models	CORRECT	`models.py`: User, Project, Repo, Note, Tag, NoteTag, NoteLink, NoteRevision, Block, CompiledPage, BoardItem
24 Alembic Migrations	CORRECT	24 `.py` files in `alembic/versions/`
2,560 Embedding Dimensions	CORRECT	`Vector(2560)` in `models.py` line 241
8 Kanban Columns	CORRECT	`BoardColumn` enum in `models.py`
14 Note Types	CORRECT	`NoteTypeEnum` in `schemas.py`
6 Board Item Types	CORRECT	`BoardItemType` enum in `models.py`