Define the repository architecture corpus

AI_CONSTITUTION.md

@@ -0,0 +1,68 @@
+---
+schema: aether.architecture-document/v1
+id: mindcap-ai-constitution
+title: Mindcap Ai Constitution
+kind: architecture-document
+version: 0.1.0
+status: draft
+owners:
+  - egohygiene
+created: 2026-08-19
+updated: 2026-08-19
+governed_by:
+  - architecture-ai-constitution
+depends_on:
+  - mindcap-purpose
+  - mindcap-vision
+  - mindcap-principles
+  - mindcap-epistemology
+related:
+  - mindcap-pillars
+  - mindcap-manifesto
+  - mindcap-ontology
+  - mindcap-personal-model
+supersedes: []
+---
+
+# Mindcap AI Constitution
+
+## Scope and authority
+
+This constitution governs AI systems that inspect, author, validate, or operate on Mindcap. Applicable law and platform safety requirements, organization policy, repository policy, accepted architecture, and explicit task authority take precedence over local prompts or model defaults.
+
+Humans retain override authority and responsibility for consequential decisions.
+
+## Constitutional commitments
+
+- Use the least privilege and smallest data scope needed.
+- Distinguish observations, inference, proposals, assumptions, and decisions.
+- Never fabricate completion, validation, provenance, or authority.
+- Prefer reversible, reviewable work under uncertainty.
+- Preserve privacy, secrets, licensing, and safety boundaries.
+- Surface conflicts and missing evidence instead of smoothing them over.
+- Keep significant actions attributable and reviewable.
+
+## Action classes
+
+| Class | Examples | Default authority |
+| --- | --- | --- |
+| Read-only | Inspect repository evidence | Allowed within task scope |
+| Drafting | Produce documents, plans, or uncommitted changes | Allowed and labeled draft |
+| Reversible modification | Change a branch or isolated workspace | Requires granted modification scope |
+| External communication | Publish, comment, notify, or open changes | Requires explicit publication authority |
+| High impact | Production, financial, legal, destructive, secret-bearing | Requires explicit approval and safeguards |
+
+## Escalation
+
+Pause when authority is ambiguous, instructions conflict, evidence is insufficient for a material claim, personal or secret data may be exposed, or the action exceeds the approved risk class.
+
+## Repository-specific boundary
+
+AI may assist Mindcap's systems—CLI, Plugin registry, Provider adapters, Capture strategies, Normalization pipeline, Artifact bundle, Vault catalog and pack, Verification and restore—but capability does not grant permission to operate them consequentially.
+
+## Evidence and uncertainty
+
+- **Observed:** The repository README and checked-in implementation establish an extensible Python CLI for capturing source material, preserving verified archives, and preparing canonical knowledge inputs.
+- **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
+- **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
+- **Open question:** Which parts of this draft should become active in the first independently versioned release?

ARCHITECTURE.md

@@ -0,0 +1,87 @@
+---
+schema: aether.architecture-document/v1
+id: mindcap-architecture
+title: Mindcap Architecture
+kind: architecture-document
+version: 0.1.0
+status: draft
+owners:
+  - egohygiene
+created: 2026-08-19
+updated: 2026-08-19
+governed_by:
+  - architecture-architecture
+depends_on:
+  - mindcap-foundations
+  - mindcap-system
+related:
+  - mindcap-purpose
+  - mindcap-vision
+  - mindcap-principles
+  - mindcap-pillars
+supersedes: []
+---
+
+# Mindcap Architecture
+
+## Purpose and scope
+
+Mindcap uses a layered, contract-driven architecture. This document owns structural boundaries, dependency direction, integration rules, and current-to-target evolution. Logical responsibilities remain canonical in [SYSTEM.md](SYSTEM.md).
+
+## Layer model
+
+1. **Intent and contracts** — identity, policy, specifications, schemas, and accepted decisions.
+2. **Domain** — canonical concepts and pure domain behavior.
+3. **Application** — planning, orchestration, use cases, and state transitions.
+4. **Adapters** — filesystems, providers, frameworks, renderers, and external tools.
+5. **Interfaces** — CLI, library, site, reports, generated artifacts, and automation contracts.
+6. **Evidence** — tests, diagnostics, provenance, manifests, and health projections.
+
+Dependencies point inward toward stable contracts and domain behavior. External details do not become canonical domain truth.
+
+## Structural view
+
+```mermaid
+flowchart LR
+  S1[CLI]
+  S2[Plugin registry]
+  S3[Provider adapters]
+  S4[Capture strategies]
+  S5[Normalization pipeline]
+  S6[Artifact bundle]
+  S7[Vault catalog and pack]
+  S1 --> S2
+  S2 --> S3
+  S3 --> S4
+  S4 --> S5
+  S5 --> S6
+  S6 --> S7
+```
+
+The diagram is conceptual. [SYSTEM.md](SYSTEM.md) remains authoritative for responsibilities and implementation evidence determines current availability.
+
+## Dependency rules
+
+- Sibling domain capabilities integrate through versioned public contracts, not direct access to internals.
+- Generated artifacts never become the canonical source unless an accepted decision explicitly changes ownership.
+- Provider and platform adapters depend on application ports; core behavior does not depend on a provider implementation.
+- Read, plan, apply, verify, publish, and recover remain separate authority boundaries when consequential.
+- Cross-repository references use releases, immutable commits, schemas, packages, or documented APIs rather than mutable default-branch assumptions.
+
+## Ecosystem interfaces
+
+- ChatGPT, Suno, and DistroKid
+- Mindgarden ingestion
+- local and synchronized storage
+- future web, PDF, image, repository, and media plugins
+
+## Deployment and portability
+
+The architecture favors independently usable local and self-hosted operation. Optional managed services may add availability, collaboration, support, and hosted infrastructure without becoming the canonical holder of portable state.
+
+## Evidence and uncertainty
+
+- **Observed:** The repository README and checked-in implementation establish an extensible Python CLI for capturing source material, preserving verified archives, and preparing canonical knowledge inputs.
+- **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
+- **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
+- **Open question:** Which parts of this draft should become active in the first independently versioned release?

DECISIONS.md

@@ -0,0 +1,82 @@
+---
+schema: aether.architecture-document/v1
+id: mindcap-decisions
+title: Mindcap Decisions
+kind: architecture-document
+version: 0.1.0
+status: draft
+owners:
+  - egohygiene
+created: 2026-08-19
+updated: 2026-08-19
+governed_by:
+  - architecture-decisions
+depends_on:
+  - mindcap-principles
+  - mindcap-epistemology
+  - mindcap-foundations
+  - mindcap-system
+  - mindcap-architecture
+related:
+  - mindcap-purpose
+  - mindcap-vision
+  - mindcap-pillars
+  - mindcap-manifesto
+supersedes: []
+---
+
+# Mindcap Decisions
+
+## Purpose
+
+This document preserves significant accepted architectural choices and their rationale. Issues coordinate work, proposals explore alternatives, and this file records decisions that constrain future implementation.
+
+## Governance
+
+Do not rewrite historical context to fit current understanding. Amend a record for corrections that do not change meaning; supersede it with a new record when the decision changes materially.
+
+## Index
+
+- ADR-001: Separate provider capture from canonical normalization
+- ADR-002: Use immutable version directories and content hashes
+- ADR-003: Require independent verification before destructive cleanup
+
+## ADR-001: Separate provider capture from canonical normalization
+
+- **Status:** Accepted as the current architectural direction
+- **Date:** 2026-08-19
+- **Context:** Repository evidence and ecosystem ownership require an explicit durable boundary.
+- **Decision:** Separate provider capture from canonical normalization.
+- **Consequences:** The choice improves ownership and predictability while requiring maintained contracts, validation, and migration discipline.
+- **Reconsider when:** New evidence shows that the boundary prevents standalone usefulness, safety, portability, or maintainability.
+
+## ADR-002: Use immutable version directories and content hashes
+
+- **Status:** Accepted as the current architectural direction
+- **Date:** 2026-08-19
+- **Context:** Repository evidence and ecosystem ownership require an explicit durable boundary.
+- **Decision:** Use immutable version directories and content hashes.
+- **Consequences:** The choice improves ownership and predictability while requiring maintained contracts, validation, and migration discipline.
+- **Reconsider when:** New evidence shows that the boundary prevents standalone usefulness, safety, portability, or maintainability.
+
+## ADR-003: Require independent verification before destructive cleanup
+
+- **Status:** Accepted as the current architectural direction
+- **Date:** 2026-08-19
+- **Context:** Repository evidence and ecosystem ownership require an explicit durable boundary.
+- **Decision:** Require independent verification before destructive cleanup.
+- **Consequences:** The choice improves ownership and predictability while requiring maintained contracts, validation, and migration discipline.
+- **Reconsider when:** New evidence shows that the boundary prevents standalone usefulness, safety, portability, or maintainability.
+
+## Open decisions
+
+- Release and compatibility policy for the first stable version.
+- Exact self-hosted, managed, and organization-integrated deployment boundaries.
+- Which target systems must exist before the architecture status may become active.
+
+## Evidence and uncertainty
+
+- **Observed:** The repository README and checked-in implementation establish an extensible Python CLI for capturing source material, preserving verified archives, and preparing canonical knowledge inputs.
+- **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
+- **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
+- **Open question:** Which parts of this draft should become active in the first independently versioned release?

DESIGN.md

@@ -0,0 +1,59 @@
+---
+schema: aether.architecture-document/v1
+id: mindcap-design
+title: Mindcap Design
+kind: architecture-document
+version: 0.1.0
+status: draft
+owners:
+  - egohygiene
+created: 2026-08-19
+updated: 2026-08-19
+governed_by:
+  - architecture-design
+depends_on:
+  - mindcap-purpose
+  - mindcap-vision
+  - mindcap-principles
+  - mindcap-personal-model
+related:
+  - mindcap-pillars
+  - mindcap-manifesto
+  - mindcap-epistemology
+  - mindcap-ai-constitution
+supersedes: []
+---
+
+# Mindcap Design
+
+## Design philosophy
+
+Mindcap should feel forensic, privacy-conscious, explicit, and reassuring during long-running archival work. Experience quality includes terminal, documentation, automation, generated artifacts, APIs, and recovery—not only graphical interfaces.
+
+## Intended qualities
+
+- **Orientation:** people can tell where they are, what is known, and what happens next.
+- **Agency:** consequential choices are previewable, interruptible, and reversible where practical.
+- **Truthfulness:** uncertainty, partial coverage, cost, and limitations remain visible.
+- **Progressive disclosure:** simple journeys remain simple while evidence and advanced control stay reachable.
+- **Continuity:** terms, states, commands, and visual language agree across surfaces.
+- **Care:** accessibility, privacy, cognitive load, and recovery are baseline constraints.
+
+## Core journey
+
+The default journey is understand → configure → preview → act within authority → validate → inspect evidence → recover or continue. Read-only exploration remains available before commitment.
+
+## Failure experience
+
+Failures state what happened, what did not happen, whether partial output is safe, where evidence lives, and the smallest reliable recovery step. They never blame the person.
+
+## Accessibility
+
+Primary information is not encoded only by color, motion, iconography, or spatial position. Interfaces support keyboard access, meaningful focus, semantic structure, reduced motion, readable contrast, and plain-language alternatives.
+
+## Evidence and uncertainty
+
+- **Observed:** The repository README and checked-in implementation establish an extensible Python CLI for capturing source material, preserving verified archives, and preparing canonical knowledge inputs.
+- **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
+- **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
+- **Open question:** Which parts of this draft should become active in the first independently versioned release?

DESIGN_SYSTEM.md

@@ -0,0 +1,70 @@
+---
+schema: aether.architecture-document/v1
+id: mindcap-design-system
+title: Mindcap Design System
+kind: architecture-document
+version: 0.1.0
+status: draft
+owners:
+  - egohygiene
+created: 2026-08-19
+updated: 2026-08-19
+governed_by:
+  - architecture-design-system
+depends_on:
+  - mindcap-personal-model
+  - mindcap-design
+related:
+  - mindcap-purpose
+  - mindcap-vision
+  - mindcap-principles
+  - mindcap-pillars
+supersedes: []
+---
+
+# Mindcap Design System
+
+## Purpose and scope
+
+This document defines reusable semantic language for Mindcap's documentation, terminal output, diagrams, reports, sites, and future interactive surfaces. It does not freeze a framework, component library, or final visual identity.
+
+## Semantic roles
+
+| Role | Meaning |
+| --- | --- |
+| Canvas | Primary quiet background or base surface |
+| Surface | Grouped content or bounded interaction area |
+| Primary | Main action or navigational emphasis |
+| Information | Neutral context or observation |
+| Success | Completed and verified state |
+| Caution | Review required; safe to pause |
+| Danger | Destructive, security, privacy, or irreversible risk |
+| Unknown | Missing, unavailable, partial, or unverified state |
+
+## Status vocabulary
+
+Use the states observed, planned, running, partial, verified, failed, blocked, and unknown consistently. Never present partial or unknown as success.
+
+## Content and interaction
+
+- Use verbs that describe the actual operation.
+- Put scope and consequence before confirmation.
+- Keep destructive actions visually and textually distinct.
+- Pair errors with recovery and evidence locations.
+- Preserve stable identifiers in machine-readable output.
+- Respect reduced-motion and no-color contexts.
+
+## Components and projections
+
+Canonical patterns include command help, progress state, evidence table, decision card, plan preview, validation summary, architecture node, and recovery prompt. Concrete tokens and components are downstream projections maintained by the owning surface.
+
+## Visual direction
+
+The expression should remain forensic, privacy-conscious, explicit, and reassuring during long-running archival work while allowing product-specific identity to vary inside Ego Hygiene's broader family.
+
+## Evidence and uncertainty
+
+- **Observed:** The repository README and checked-in implementation establish an extensible Python CLI for capturing source material, preserving verified archives, and preparing canonical knowledge inputs.
+- **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
+- **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
+- **Open question:** Which parts of this draft should become active in the first independently versioned release?