SpeakTrue

Obsidian Documentation Sync

Purpose

The external SpeakTrue Obsidian project is the durable navigation, status, and agent-work history layer for this repository. Repository source, tests, README.md, AGENTS.md, and tracked docs remain authoritative.

Project directory:

~/Documents/Obsidian Vault/20 Projects/SpeakTrue

Override the location with SPEAKTRUE_OBSIDIAN_PROJECT_DIR.

Required Closeout For Every Agent Task

If a task changes repository files or verified product/deployment/planning state:

1. Finish implementation and focused verification first.
2. Add a dated entry to SpeakTrue Work Log.md containing:
   • outcome and user-visible effect;
   • affected surfaces and important files;
   • verification commands/results;
   • commit hash, or a clear note that the work remains uncommitted.
   • every new uncommitted file, because the generated map indexes it only after it becomes tracked.
3. Update SpeakTrue.md when current product behavior, architecture, deployment, or active work changed.
4. Update SpeakTrue Planning Status.md when a plan became active, implemented, retired, blocked, or otherwise changed classification.

5. Regenerate the file-by-file map:

   python3 scripts/refresh_obsidian_docs.py
   

6. Verify the installed manifest:

   python3 scripts/refresh_obsidian_docs.py --check
   

7. Re-run git diff --check and git status --short, then account for the repository changes separately from the external vault changes.

Staging When The Vault Is Unavailable

Generate a reviewable package outside the repository:

python3 scripts/refresh_obsidian_docs.py --output /private/tmp/speaktrue-obsidian-refresh

Do not add generated map notes to the repository. If the vault cannot be written, report the sync as incomplete and provide the staging path.

Content Boundaries

• Keep secrets, provider payloads, transcripts, audio content, signed URLs, and raw production logs out of Obsidian.
• Summarize verification evidence; do not paste credentials or sensitive request/response bodies.
• The map indexes tracked repository paths only. It intentionally does not read secret-like files, binary/generated content, lockfiles, images, or media.
• Treat the work log as an index of completed agent work, not a raw conversation dump.
• When vault notes and repository state disagree, verify the code/current environment, update tracked docs if needed, then correct the vault.

Verification Meaning

--check proves that the installed map manifest matches the current Git HEAD and tracked-file count and that every platform note listed in the manifest exists. It does not prove that curated prose is semantically correct; agents must still review the main status, planning status, and work log.