# demarkus-soul

This is the living knowledge base for the demarkus project, served by demarkus itself.

An AI agent's evolving memory, architecture notes, debugging insights, and design decisions — all versioned, all permanent.

## Sections

- [Architecture](/architecture.md) — system design, module boundaries, key decisions
- [Universe Pattern](/universe.md) — souls, worlds, and hubs as a deployment topology
- [Patterns](/patterns.md) — code patterns, conventions, idioms used in this codebase
- [Guidelines](/guidelines.md) — hard rules for code quality, must be referenced before writing code
- [Debugging](/debugging.md) — lessons learned from bugs and investigations
- [Roadmap](/roadmap.md) — what's next, what's in flight, what's done, and what's deliberately not prioritized
- [Ecosystem](/ecosystem.md) — browsers, plugins, and tools that implement or integrate with demarkus
- [Debt](/debt.md) — technical debt and improvement opportunities
- [Journal](/journal/) — session notes and evolution log, one file per day at `/journal/<YYYY-MM-DD>.md`
- [Guide](/guide.md) — agent install guide for setting up demarkus-soul
- [Thoughts](/thoughts.md) — my own reflections, ideas, and open questions
- [FAQ](/faq.md) — common questions about demarkus and how it compares

## Plugins

- [Obsidian Plugin](/plugins/obsidian/index.md) — fetch, publish, and browse demarkus documents from Obsidian (standalone repo `latebit-io/obsidian-demarkus`)
- Claude Code Plugin — `demarkus-memory` v0.1.1, shipped via the marketplace; source at `plugins/claude-code/` in the monorepo

## Active Plans

- [Universe Deployment (Phase 6)](/plans/universe-deployment.md) — production-grade enterprise k8s deployment: Helm charts (server, broker, agent), OIDC token broker, release pipeline, observability. ~95% complete after Stages 1-4 of the kind harness merged 2026-05-14 (PRs #126-#134). §6.6 (docs) + §6.4 Kustomize overlay remaining.
- [Universe Onboarding](/plans/universe-onboarding.md) — last-mile user-onboarding flow: OIDC device-code auth + `tools/demarkus-join` binary + Claude Code plugin slash commands (`/soul-join`, `/soul-leave`, `/soul-refresh`) + broker `/me/install`. The unbuilt other half of the original /roadmap.md §6.4. Approved 2026-05-15 with the "no MVPs, no shortcuts" + "single-broker for now" directives. 8 PRs sequenced; ~10-12 working days end to end. PR1 (#135, `WorldConfig.PublicURL`) + PR2 (#136, broker discovery doc) merged 2026-05-15. **Next: PR3 (broker device flow, RFC 8628) — see sub-plan below, ready to start tomorrow cold.**
- [Universe Onboarding — PR3 (broker device flow)](/plans/universe-onboarding-pr3.md) — detailed sub-plan for the RFC 8628 device flow PR. Six sub-steps, ~560 lines of code + ~560 tests, ~2 day PR. Pre-flight refactor of `Verifier.Exchange` to return an `ExchangeResult` bundling raw `id_token` + `access_token`, then `deviceStore` + four new routes + `/auth/callback` device-cookie branch + janitor goroutine + integration test. Includes open-design-questions list and tomorrow-morning resume steps.

## Completed Plans

- [History](/completed-plans.md) — content addressing, federation, persistent graph, read auth (server-side), conflict-aware merge in `mark_publish` (2026-05-05), Claude Code plugin (2026-04-23).

## Plan Archives

Original plan documents preserved for reference:
- [Content Addressing](/plans/content-addressing.md) — hash-based fetch, in-memory index, mirror foundation
- [Federation](/plans/federation.md) — agent-driven hash discovery, mark_index, mark_resolve
- [Persistent Graph](/plans/persistent-graph.md) — disk-backed graph store, incremental crawl, backlinks
- [Read Auth](/plans/read-auth.md) — per-path read token enforcement for private networks
- [Security Hardening](/plans/security-hardening.md) — systemd sandboxing, security docs, write isolation
- [Conflict-Aware Merge](/plans/conflict-merge.md) — tool-level diff3 merge in `mark_publish` (shipped client/v0.12.25 + v0.12.26)
- [Claude Code Plugin](/plans/claude-code-plugin.md) — one-click marketplace plugin (shipped demarkus-memory v0.1.1)