You are helping me design the foundation for a deeply personal AI assistant.

This is not a SaaS product and it does not need to generalise to thousands of users. It should become increasingly useful for one person, while keeping accumulated knowledge independent from any single AI model, agent runtime or vendor.

Do not start by building features.

First create the architecture, documentation and minimal technical foundation that future agents can safely extend.

## Core principles

1. My data and accumulated context remain mine.
2. AI models are replaceable reasoning layers.
3. The orchestration/gateway layer should also remain replaceable.
4. Stable interfaces should separate models, tools and the knowledge layer.
5. Source evidence is more important than confident inference.
6. "No result found" must never silently become "this does not exist".
7. Facts, inferences, suggestions and actions must remain distinguishable.
8. Read operations and actions with consequences must have different policies.
9. Prefer existing applications and data sources over creating another dashboard.
10. Optimise for continuity: help me reconstruct less context myself.
11. Build only what is justified by an actual use case.
12. Document important architectural decisions before they disappear into code.

## Start with discovery

Inspect the existing environment before proposing architecture.

Identify:

- operating system and devices
- existing repositories
- databases
- notes
- files and cloud storage
- email
- calendars
- tasks/reminders
- contacts
- browser context
- messaging
- audio/transcription sources
- existing AI tools
- MCP servers or comparable interfaces
- local models
- automation mechanisms
- existing credentials and permission boundaries

Do not expose secrets or private content in documentation.

Separate:

- available now
- partially available
- planned
- unknown / not yet verified

Never describe a capability as working until it has been validated.

## Define the questions first

Create `docs/USE_CASES.md`.

Start with actual questions the assistant should eventually answer, for example:

- What deserves my attention right now?
- Which conversations probably require something from me?
- What am I waiting on someone else for?
- What was I working on yesterday and where should I continue?
- Prepare me for my next meeting.
- What did we previously decide about this?
- Which source supports that conclusion?
- What changed since I last looked at this?
- What does my day look like and where is there still room?

For every use case record:

- user question
- required sources
- minimum evidence
- useful optional context
- expected output
- uncertainty conditions
- possible actions
- actions requiring approval
- acceptance test

Do not invent sources merely to make a use case possible.

## Create the architecture documentation

Create at minimum:

docs/
  README.md
  VISION.md
  PRINCIPLES.md
  USE_CASES.md
  ARCHITECTURE.md
  DATA_SOURCES.md
  KNOWLEDGE_MODEL.md
  RETRIEVAL.md
  PROVENANCE.md
  SECURITY.md
  PERMISSIONS.md
  OBSERVABILITY.md
  TESTING.md
  ROADMAP.md
  CURRENT_STATE.md
  adr/

### VISION.md

Explain:

- what cognitive burden this system should remove
- what it deliberately will not become
- why durable context must remain independent
- what success looks like for one person

### ARCHITECTURE.md

Define clear replaceable layers:

AI client / model
↓ tool protocol / interface
↓ orchestration / execution layer
↓ source adapters
↓ retrieval + structured knowledge + graph
↓ durable personal data

Describe interfaces between layers rather than coupling them directly.

### DATA_SOURCES.md

For every source record:

- owner
- adapter
- access method
- read/write capability
- freshness
- authoritative fields
- known limitations
- provenance mechanism
- permission requirements
- failure behaviour

### KNOWLEDGE_MODEL.md

Design the initial entity model.

Consider entities such as:

- Person
- Organisation
- Project
- Conversation
- Message
- Meeting
- Document
- Note
- Task
- Decision
- Commitment
- Topic
- Source

Do not create relationships merely because two entities appear together.

Every durable relationship should record provenance and confidence where relevant.

### RETRIEVAL.md

Design retrieval as a pipeline rather than "vector search".

Document:

1. query understanding
2. hard constraints
3. lexical retrieval
4. semantic retrieval
5. structured retrieval
6. graph retrieval
7. candidate fusion
8. reranking
9. freshness
10. deduplication
11. context packaging
12. answerability checks
13. bounded iterative retrieval

Define when each layer is useful and when it should abstain.

### PROVENANCE.md

Define how every important claim can be traced back to:

- original source
- source identifier
- date/time
- document section/page/message/timestamp where possible
- extraction version
- derived relationship where relevant

A generated answer is not itself a source.

### SECURITY.md / PERMISSIONS.md

Separate:

READ
WRITE
EXTERNAL EFFECT
ADMINISTRATIVE

Default to read-only.

Actions such as sending mail, modifying calendars, changing files, controlling devices or deploying code must have explicit policies.

Document where human approval is required.

### OBSERVABILITY.md

Define measurable health for:

- source availability
- source freshness
- extraction coverage
- embedding/index coverage
- structured enrichment backlog
- graph lag
- failed retrieval
- latency
- tool failures
- schema changes
- agent actions

Unknown must remain a valid system state.

### CURRENT_STATE.md

Create an evidence-based matrix:

| Capability | State | Evidence | Limitation | Next validation |
|---|---|---|---|---|

Use only:

- validated
- implemented_not_validated
- partial
- planned
- blocked
- unknown

Do not use vague labels such as "done" without evidence.

## Architecture Decision Records

Create ADRs for important choices.

At minimum consider:

- local-first vs cloud-first
- durable knowledge store
- vector store strategy
- tool/interface protocol
- orchestration layer
- source provenance
- approval model
- knowledge graph strategy
- model independence
- personal-data privacy

Each ADR should contain:

Context
Decision
Alternatives considered
Consequences
Reversibility

## Agent operating instructions

Create `AGENTS.md`.

It should tell future coding agents to:

- read the architecture and current-state docs first
- inspect before changing
- preserve existing interfaces unless intentionally versioned
- never silently widen permissions
- never claim validation from implementation alone
- add tests with every capability
- update documentation when architecture changes
- prefer bounded changes
- record important decisions as ADRs
- distinguish source facts from derived conclusions
- keep private content out of logs and fixtures
- leave the repository in a resumable state

## Minimal repository foundation

Only after the documentation exists, create the smallest useful boilerplate.

Prefer something like:

src/
  adapters/
  retrieval/
  knowledge/
  orchestration/
  permissions/
  observability/
tests/
  unit/
  integration/
  fixtures/
docs/
config/
scripts/

Do not implement twenty integrations.

Build:

- one source adapter interface
- one tool/interface contract
- one retrieval interface
- one provenance model
- one permission model
- health/status primitives
- test fixtures
- configuration loading
- structured logging

Then implement ONE narrow end-to-end vertical slice.

For example:

"Find one known document and return a source-backed answer."

The slice must prove:

source → adapter → retrieval → provenance → assistant context → answer

Only then expand.

## Roadmap

Build the roadmap from user value, not from technical novelty.

Each roadmap item must contain:

- user problem
- required sources
- dependencies
- implementation slice
- validation method
- failure conditions
- privacy impact
- definition of done

Prefer one validated vertical slice over ten partially built subsystems.

## Final output

When finished, return:

1. discovered current state
2. proposed architecture
3. generated documentation tree
4. key architectural decisions
5. repository skeleton
6. first end-to-end slice
7. tests created
8. unresolved risks
9. assumptions requiring my confirmation
10. next three bounded implementation steps

Do not continue expanding functionality merely because there is time left.

Build a foundation another agent can understand tomorrow without requiring the original conversation that created it.