Architecture

This repository implements a file-based research workflow (no databases) with GitHub-native coordination.

Core objects

Documents (doc_*)

  • vault/owned/<doc_id>/doc.md + transcript.md
  • vault/references/<doc_id>/doc.md (no fulltext)
  • vault/raw/<doc_id>/... originals

Ideas (idea_*)

  • One file per atomic idea: ideas/<idea_id>.md
  • Each idea lists sources {doc, locator, quote?}

Projects (proj_*)

  • projects/<proj_id>/project.md
  • idea_ids links to atomic ideas
  • Kanban status: backlog / active / paused / done

Lab artifacts

  • Notebooks: lab/notebooks/*.md
  • Blackboards: lab/blackboards/*.md
  • When finished, archive them as documents:
    • python tools/townctl.py archive-md --source-md lab/notebooks/<nb_id>.md --title "..."
    • archived as doc_* in vault/owned/

Publishing

  • Blog posts in docs/_posts/
  • Post frontmatter includes idea_ids and doc_ids
  • Posts are deployed to GitHub Pages from main:/docs.

Automation (GitHub Actions)

Deterministic:

  • town-maintenance.yml: lint + (re)index + export site pages, scheduled and on push.
  • GitHub Pages builds the Jekyll site directly from docs/ (no workflow required).

Agentic (commit-to-main, issue-driven):

  • Planned workflows (not yet added): librarian, idea-miner, writer, project, evaluator.

Optional (GitHub Next Agentic Workflows / gh-aw):

  • .github/workflows/town-*.md are gh-aw sources designed to compile into .lock.yml workflows. They are primarily for triage/collect/evaluate in issue comments.

File-based cross references

The catalog/ directory is regenerated by python tools/townctl.py index:

  • documents.yml/.md
  • ideas.yml/.md
  • projects.yml/.md
  • xref.yml (doc↔idea↔project↔post mappings)
  • kanban.md
  • unused-ideas.md

Site exports:

  • python tools/townctl.py export-site can inject catalog tables into published pages, but the blog is currently post-centric.