Add design doc, restructure project docs

AGENTS.md

@@ -0,0 +1 @@
+README.md

CLAUDE.md

@@ -0,0 +1 @@
+README.md

GEMINI.md

@@ -0,0 +1 @@
+README.md

HUMANS.md

@@ -4,34 +4,35 @@ Welcome. This document is for humans who want a quick, honest overview.
 
 ## What is Aiome?
 
-Aiome is an early-stage CLI exploring how multiple AI agents could collaborate on software work. The long-term vision is
-role-based agents coordinating through artifacts like code, tests, and issues. The current reality is much smaller.
+Aiome is a CLI that automatically generates, maintains, and serves multi-scale knowledge about a codebase — so that AI
+agents get exactly the right context for any task.
 
-## Current State
-
-Right now the CLI is a simple REPL that echoes input. That’s it. Anything beyond that is a direction, not a promise.
+The core idea: AI agents have limited context windows and no memory between sessions. Hand-written context files
+(CLAUDE.md, .cursorrules) work for small projects but don’t scale. Aiome analyzes your codebase’s structure, identifies
+natural subsystem boundaries, generates knowledge at multiple resolutions, and serves the right resolution for each
+task.
 
-## Why It Exists
+## Current State
 
-We want to see if a small set of lightweight principles can help AI agents do useful work without heavy process. We
-expect the project structure to evolve based on real usage.
+Early stage. The CLI is a REPL that echoes input. The architecture is designed
+([docs/design-doc.md](./docs/design-doc.md)) but not yet implemented. Next step is Phase 1: static and temporal
+coupling analysis.
 
-## Quick Start (Today)
+## Quick Start
 
 ```bash
-# Run locally
-cargo run
-
-# Or install locally
-cargo install --path .
+cargo run                   # Start the REPL
+cargo install --path .      # Or install locally as `aiome`
 ```
 
-This starts a prompt. Type a line, it echoes back. Use Ctrl+D (Unix/Linux/macOS) or Ctrl+Z then Enter (Windows) to exit.
+Ctrl+D to exit.
 
-## Where to Look Next
+## Where to Look
 
-- **README.md**: Direction for agents and contributors
-- **src/main.rs**: The current CLI entry point
+- **[README.md](./README.md)** — Project constitution (conventions, commands, repo layout)
+- **[docs/design-doc.md](./docs/design-doc.md)** — Architecture: Analyze → Generate → Serve
+- **[docs/vision.md](./docs/vision.md)** — Foundational ideas (BRAIN pattern, stigmergy, cognitive scaffolding)
+- **src/main.rs** — The current CLI entry point
 
 ## The Name
 

README.md

@@ -2,71 +2,59 @@
 
 > **Human readers**: See [HUMANS.md](./HUMANS.md) for a gentler introduction.
 
-Aiome is an early-stage CLI exploring how multiple AI agents can collaborate on software work. This README is
-intentionally lightweight: it sets direction without pretending the project is further along than it is.
+Aiome automates multi-scale knowledge infrastructure for codebases — so that any AI agent, at any moment, can load
+exactly the context it needs at exactly the right resolution. See [docs/design-doc.md](./docs/design-doc.md) for the
+full architecture. See [docs/vision.md](./docs/vision.md) for the foundational ideas.
 
 ---
 
-## Current State (Reality Wins)
+## Current State
 
-Right now this repository is small and experimental. The CLI is a simple REPL that echoes input. Anything beyond that is
-directional, not guaranteed.
+The CLI is a REPL that echoes input. Everything below is direction, not implemented.
 
-If this document drifts from the code, update the document.
+The next milestone is Phase 1 (Analyze): static + temporal coupling analysis producing an entanglement map and partition
+structure. No LLM needed. See the design doc’s "CLI" section for the phased build plan.
 
 ---
 
-## Direction (Not Mandates)
+## Repository Layout
 
-These are the ideas we want to grow toward, without locking ourselves into a rigid process:
-
-- **Roles are verbs.** Treat agents as functions, not personas.
-- **Bounded work.** Keep scope small, context limited, and changes reversible.
-- **Coordination via artifacts.** Prefer code, tests, issues, and notes over chatty handoffs.
-- **Transparency.** If you’re unsure, say so and leave a clear trail.
-- **Locality.** Touch what you must, avoid sweeping refactors.
-
----
-
-## Potential Roles (Names May Change)
-
-These are placeholders for how we might structure work over time:
-
-- **plan** — identify work worth doing
-- **implement** — make a focused change
-- **review** — check correctness and scope
-- **debug** — fix a concrete issue
-- **refactor** — improve structure without behavior changes
-- **retrospect** — reflect and propose process tweaks
-
-Treat these as a vocabulary, not a contract.
+```
+├── Cargo.toml              # Rust 2024 edition, rustyline dependency
+├── src/
+│   └── main.rs             # CLI entry point: REPL loop
+├── docs/
+│   ├── design-doc.md       # Architecture: Analyze → Generate → Serve
+│   └── vision.md           # Foundational ideas: BRAIN pattern, stigmergy, scaffolding
+├── HUMANS.md               # Human-oriented overview
+└── .github/workflows/
+    └── ci.yml              # CI: fmt, clippy, test
+```
 
 ---
 
-## Working Here (Lightweight)
+## Conventions
 
-- Prefer small, readable changes over perfect systems.
-- If you add tests, run `cargo test`. If you add formatting or linting conventions, document them.
-- If you want to introduce new process or guardrails, open an issue first so humans can weigh in.
+- **Rust 2024 edition.** `cargo fmt`, `cargo clippy -- -D warnings`, `cargo test` must all pass. CI enforces this.
+- **Small changes.** Prefer focused commits over sweeping refactors.
+- **Coordination via artifacts.** Code, tests, issues, and PRs over chatty handoffs.
+- **Honesty over aspiration.** If this document drifts from the code, update the document.
 
 ---
 
-## Repository Snapshot (Today)
+## Commands
 
-This is the current layout and may evolve:
-
-```
-repo-root/
-├── Cargo.toml
-├── src/
-│   └── main.rs
-├── HUMANS.md
-└── README.md
+```bash
+cargo run                   # Start the REPL
+cargo test                  # Run tests (none yet)
+cargo fmt                   # Format code
+cargo clippy --all-targets --all-features -- -D warnings  # Lint (matches CI)
+cargo install --path .      # Install locally as `aiome`
 ```
 
 ---
 
-## Final Note
+## What’s Next
 
-Let the structure emerge from the work. Keep the docs honest. Make it easy for the next person to understand what
-changed and why.
+Phase 1 of the design doc: `aiome init` producing an entanglement map and partition structure from static analysis
+(tree-sitter) and git history (git2). Key dependencies to add: `tree-sitter`, `git2`, `petgraph`, `clap`.