Define the repository architecture corpus

AI_CONSTITUTION.md

@@ -0,0 +1,68 @@
+---
+schema: aether.architecture-document/v1
+id: renderflow-ai-constitution
+title: Renderflow 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:
+  - renderflow-purpose
+  - renderflow-vision
+  - renderflow-principles
+  - renderflow-epistemology
+related:
+  - renderflow-pillars
+  - renderflow-manifesto
+  - renderflow-ontology
+  - renderflow-personal-model
+supersedes: []
+---
+
+# Renderflow AI Constitution
+
+## Scope and authority
+
+This constitution governs AI systems that inspect, author, validate, or operate on Renderflow. 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 Renderflow's systems—Specification loader, Transform registry, Graph planner, Execution engine, Artifact and cache manager, CLI and Rust library, Documentation and release surface—but capability does not grant permission to operate them consequentially.
+
+## Evidence and uncertainty
+
+- **Observed:** The repository README and checked-in implementation establish a specification-driven Rust rendering engine that plans and executes reusable transformation graphs for publication-ready artifacts.
+- **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: renderflow-architecture
+title: Renderflow 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:
+  - renderflow-foundations
+  - renderflow-system
+related:
+  - renderflow-purpose
+  - renderflow-vision
+  - renderflow-principles
+  - renderflow-pillars
+supersedes: []
+---
+
+# Renderflow Architecture
+
+## Purpose and scope
+
+Renderflow 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[Specification loader]
+  S2[Transform registry]
+  S3[Graph planner]
+  S4[Execution engine]
+  S5[Artifact and cache manager]
+  S6[CLI and Rust library]
+  S7[Documentation and release surface]
+  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
+
+- Beacon document projects
+- Reflector publications
+- Flow orchestration
+- Pandoc, FFmpeg, Tera, and optional AI providers
+
+## 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 a specification-driven Rust rendering engine that plans and executes reusable transformation graphs for publication-ready artifacts.
+- **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: renderflow-decisions
+title: Renderflow 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:
+  - renderflow-principles
+  - renderflow-epistemology
+  - renderflow-foundations
+  - renderflow-system
+  - renderflow-architecture
+related:
+  - renderflow-purpose
+  - renderflow-vision
+  - renderflow-pillars
+  - renderflow-manifesto
+supersedes: []
+---
+
+# Renderflow 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: Use a directed acyclic graph as the canonical execution model
+- ADR-002: Keep YAML specifications declarative and versionable
+- ADR-003: Expose both a standalone CLI and reusable Rust library
+
+## ADR-001: Use a directed acyclic graph as the canonical execution model
+
+- **Status:** Accepted as the current architectural direction
+- **Date:** 2026-08-19
+- **Context:** Repository evidence and ecosystem ownership require an explicit durable boundary.
+- **Decision:** Use a directed acyclic graph as the canonical execution model.
+- **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: Keep YAML specifications declarative and versionable
+
+- **Status:** Accepted as the current architectural direction
+- **Date:** 2026-08-19
+- **Context:** Repository evidence and ecosystem ownership require an explicit durable boundary.
+- **Decision:** Keep YAML specifications declarative and versionable.
+- **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: Expose both a standalone CLI and reusable Rust library
+
+- **Status:** Accepted as the current architectural direction
+- **Date:** 2026-08-19
+- **Context:** Repository evidence and ecosystem ownership require an explicit durable boundary.
+- **Decision:** Expose both a standalone CLI and reusable Rust library.
+- **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 a specification-driven Rust rendering engine that plans and executes reusable transformation graphs for publication-ready artifacts.
+- **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: renderflow-design
+title: Renderflow 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:
+  - renderflow-purpose
+  - renderflow-vision
+  - renderflow-principles
+  - renderflow-personal-model
+related:
+  - renderflow-pillars
+  - renderflow-manifesto
+  - renderflow-epistemology
+  - renderflow-ai-constitution
+supersedes: []
+---
+
+# Renderflow Design
+
+## Design philosophy
+
+Renderflow should feel precise, editorial, calm, and transparent about conversion quality. 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 a specification-driven Rust rendering engine that plans and executes reusable transformation graphs for publication-ready artifacts.
+- **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: renderflow-design-system
+title: Renderflow 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:
+  - renderflow-personal-model
+  - renderflow-design
+related:
+  - renderflow-purpose
+  - renderflow-vision
+  - renderflow-principles
+  - renderflow-pillars
+supersedes: []
+---
+
+# Renderflow Design System
+
+## Purpose and scope
+
+This document defines reusable semantic language for Renderflow'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 precise, editorial, calm, and transparent about conversion quality 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 a specification-driven Rust rendering engine that plans and executes reusable transformation graphs for publication-ready artifacts.
+- **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?