docs: rewrite README as portfolio-facing project overview #244

Merged

forgejo_admin merged 2 commits from 243-polish-readme-md-for-portfolio-facing-pr into main

2026-03-28 22:13:45 +00:00

forgejo_admin commented

2026-03-28 22:09:24 +00:00

Owner

Summary

Replaces the internal-facing README (which referenced outdated SQLite architecture and operational details) with a polished, recruiter-ready document that leads with what the platform does and highlights engineering scope.

Changes

README.md — Full rewrite. New structure: title/one-liner, tech stack table, key features (block model, kanban, Forgejo sync, hybrid search, MCP integration, note graph), API surface summary (47 endpoints / 8 modules), data model diagram, project structure tree, development commands, related repos.

Test Plan

Documentation-only change, no code modified
Verify all stated facts against codebase: 685+ tests (confirmed via pytest --co), 47 endpoints (confirmed via route decorator count), 22 migrations (confirmed via alembic/versions/), 12 models (confirmed via models.py), 8 route modules (confirmed via routes/)
Verify markdown renders correctly on Forgejo

Review Checklist

Facts verified against codebase (test count, endpoint count, migration count, model count)
No internal URLs or secrets exposed
Professional tone suitable for external review
Markdown structure renders cleanly

None — documentation-only change.

Closes #243

## Summary Replaces the internal-facing README (which referenced outdated SQLite architecture and operational details) with a polished, recruiter-ready document that leads with what the platform does and highlights engineering scope. ## Changes - `README.md` — Full rewrite. New structure: title/one-liner, tech stack table, key features (block model, kanban, Forgejo sync, hybrid search, MCP integration, note graph), API surface summary (47 endpoints / 8 modules), data model diagram, project structure tree, development commands, related repos. ## Test Plan - Documentation-only change, no code modified - Verify all stated facts against codebase: 685+ tests (confirmed via `pytest --co`), 47 endpoints (confirmed via route decorator count), 22 migrations (confirmed via `alembic/versions/`), 12 models (confirmed via `models.py`), 8 route modules (confirmed via `routes/`) - Verify markdown renders correctly on Forgejo ## Review Checklist - [x] Facts verified against codebase (test count, endpoint count, migration count, model count) - [x] No internal URLs or secrets exposed - [x] Professional tone suitable for external review - [x] Markdown structure renders cleanly ## Related Notes None — documentation-only change. ## Related Closes #243

forgejo_admin added 1 commit

2026-03-28 22:09:24 +00:00

docs: rewrite README as portfolio-facing project overview ac2542c73f

Replace the internal-facing README (which referenced outdated SQLite
architecture) with a polished, recruiter-ready document that leads with
what the platform does and highlights engineering scope: 685+ tests,
47 endpoints, block-first content model, hybrid semantic search, and
kanban board API with Forgejo sync.

Closes #243

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin added 1 commit

2026-03-28 22:10:25 +00:00

fix: correct test module count and ORM description in README 3d0dc27089

- 32 test modules -> 29 (actual count of test_*.py files)
- Remove "async-compatible" from SQLAlchemy description — the database
  layer uses synchronous sessions, not async

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented

2026-03-28 22:10:38 +00:00

Author

Owner

QA Review — PR #244

Findings

Fixed (pushed in 3d0dc27):

Test module count was wrong. README stated "32 test modules" but ls tests/test_*.py | wc -l returns 29. Corrected to 29.
ORM description was misleading. "async-compatible" implied async SQLAlchemy usage, but database.py uses synchronous sessions exclusively. Changed to "declarative mapped columns."

Verified accurate:

685+ tests (pytest --co confirms 685)
47 endpoints (route decorator count confirmed)
22 Alembic migrations (alembic/versions/ count confirmed)
12 SQLAlchemy models (models.py confirmed)
8 route modules (routes/ listing confirmed)
2560-dim embeddings (Vector(2560) in models.py confirmed)
All feature descriptions match actual codebase behavior

Note: Related Repositories links point to internal Forgejo URLs. A recruiter without Tailscale access cannot follow them. This is acceptable if the repo itself is accessed via Forgejo (same network), but worth noting if the repo is ever mirrored to a public host.

VERDICT: APPROVED

## QA Review — PR #244 ### Findings **Fixed (pushed in 3d0dc27):** 1. **Test module count was wrong.** README stated "32 test modules" but `ls tests/test_*.py | wc -l` returns 29. Corrected to 29. 2. **ORM description was misleading.** "async-compatible" implied async SQLAlchemy usage, but `database.py` uses synchronous sessions exclusively. Changed to "declarative mapped columns." **Verified accurate:** - 685+ tests (pytest --co confirms 685) - 47 endpoints (route decorator count confirmed) - 22 Alembic migrations (alembic/versions/ count confirmed) - 12 SQLAlchemy models (models.py confirmed) - 8 route modules (routes/ listing confirmed) - 2560-dim embeddings (Vector(2560) in models.py confirmed) - All feature descriptions match actual codebase behavior **Note:** Related Repositories links point to internal Forgejo URLs. A recruiter without Tailscale access cannot follow them. This is acceptable if the repo itself is accessed via Forgejo (same network), but worth noting if the repo is ever mirrored to a public host. ### VERDICT: APPROVED