Skip to content

Rewrite README to match the current architecture#21

Merged
johnnyclem merged 1 commit into
mainfrom
claude/readme-review-update-593op4
Jul 21, 2026
Merged

Rewrite README to match the current architecture#21
johnnyclem merged 1 commit into
mainfrom
claude/readme-review-update-593op4

Conversation

@johnnyclem

Copy link
Copy Markdown
Owner

What Changed

  • Rewrote README.md from scratch to match the current codebase instead of a stale earlier API surface.
  • Replaced the outdated tool-by-tool reference (save_concept_as_thoughtForm, convert_concept_from_*, etc.) with the tools actually registered in src/server.ts: save_concept, read_concept, delete_concept, list_concepts, batch_save_concepts, search_concepts, convert_concept, embed_text, health_check, get_stats, agentvault_backup, and the optional vault_* tools.
  • Fixed the vector dimension inconsistency (README mixed 384 and 768; the actual value is VECTOR_DIMENSION = 384, all-MiniLM-L6-v2).
  • Corrected the clone URL (yourusername/politicianjohnnyclem/polytician).
  • Documented the real env-var-driven configuration (POLYTICIAN_* variables in src/config.ts), namespaces + optimistic concurrency (expectedVersion), the Postgres/pgvector backend, and AES-256-GCM encrypted PolyVault backups.
  • Clarified that the Python sidecar is optional (FAISS rebuild + PolyVault bundle ops only) and never auto-spawned, replacing installation steps that implied it was required for embeddings/NER.
  • Added CI/npm/license/Node badges, a corrected architecture diagram, and accurate Docker Compose / Kubernetes deployment sections.
  • Removed the outdated step-by-step tutorials that referenced tools/fields no longer in the codebase.

Why

The previous README described an earlier API surface and was already flagged in its own text as "pending a rewrite" — several examples referenced tools, field names, and a 768-dim vector size that don't exist in the current implementation, which would actively mislead new users and integrators.

Validation

  • Documentation-only change; no code paths modified.
  • Local checks run (describe below) — not applicable, no source changes.
# N/A — README.md only

Risks / Rollback

  • Risk level: low
  • Rollback plan: revert this commit; no code or schema changes are included.

Notes for Reviewers

  • PolyVault guardrails checklist is out of scope — this PR only touches README.md.

Generated by Claude Code

The old README described a stale API (save_concept_as_thoughtForm-style
tools, 768-dim vectors, a Python sidecar doing embeddings/NER) that no
longer matches src/server.ts. Rewrites the tool reference against the
actual registered tools (save_concept, search_concepts, convert_concept,
vault_* etc.), fixes the vector dimension to 384, documents real env-var
config, Postgres/pgvector support, encrypted backups, and adds badges,
Docker/k8s deployment notes, and a corrected clone URL.
@johnnyclem
johnnyclem merged commit 1df3b89 into main Jul 21, 2026
7 checks passed
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.

2 participants