Project docs v2

[kenwalger]

No description provided.

[greptile-apps]

Greptile Summary

This PR adds a comprehensive second-generation documentation suite covering the Sovereign SDK's architecture, strategy, and real-world deployment blueprints — 21 new files totalling 666 lines across architecture/, strategy/, and a new VISION.md manifesto.

• Architecture docs introduce four boundary specifications (Ingestion, Edge, Airlock, Vault) each with embedded Mermaid diagrams, alongside five industry blueprint READMEs (IoT, manufacturing, museum, warehouse, developer workstation).
• Strategy docs cover the product thesis, SDK engineering philosophy, commercial model, market validation, and a three-horizon roadmap.
• Key issues: Component naming is inconsistent across documents — sovereign-sensor / sovereign-sdk-sensor / sovereign-vault are used interchangeably — and the four standalone .mmd diagram files duplicate their corresponding embedded Mermaid blocks verbatim, creating a two-source-of-truth maintenance risk.

Confidence Score: 4/5

Safe to merge as documentation, but the component naming inconsistency should be resolved before the docs are published or shared externally.

The naming inconsistency between sovereign-sdk-* and sovereign-* (e.g., sovereign-vault vs sovereign-sdk-vault) is the most consequential issue — a developer following the roadmap or product thesis to install packages could target the wrong package name. The remaining findings (duplicate .mmd files, stray placeholder symbol, missing fastapi from warehouse diagram) are editorial and do not affect runtime behavior.

strategy/product_thesis.md and strategy/roadmap.md carry the naming inconsistency; the four architecture/diagrams/*.mmd files are exact duplicates of their parent .md counterparts and need a decision on whether to keep or remove them.

Important Files Changed

Filename	Overview
strategy/product_thesis.md	Uses short sovereign-* package names (no -sdk- infix) inconsistent with other docs that use sovereign-sdk-*; will mislead developers trying to locate packages.
strategy/roadmap.md	Mixes naming conventions within the same document — Horizon 1 uses sovereign-sdk-* while Horizon 3 uses sovereign-vault (no -sdk-), compounding the naming inconsistency found across the PR.
architecture/diagrams/airlock_outbound.mmd	Exact duplicate of the Mermaid block in architecture/airlock.md; all four .mmd files in this directory have the same duplication issue, creating a two-source-of-truth maintenance problem.
architecture/examples/warehouse/README.md	Mentions sovereign-sdk-fastapi as a Failure Moat component in prose but omits it from the topology diagram and from all other example blueprints, creating an inconsistency.
architecture/examples/museum/README.md	Well-structured blueprint with a stray (§) placeholder symbol in the execution description of the Local Gatekeeper component.
VISION.md	New top-level manifesto introducing the Sovereign Systems philosophy, three pillars, and a high-level Mermaid architecture diagram. Clean and consistent.
architecture/airlock.md	New Airlock boundary architecture doc with inline Mermaid diagram; content is clear and consistent with its section.
architecture/edge.md	New Edge boundary doc with pipeline topology diagram and three high-assurance invariants.
strategy/commercial_strategy.md	Clearly lays out the open-source wedge and commercial monetization model with PyPI links; uses sovereign-sdk-* naming consistently within this file.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Ingestion ["Ingestion Boundary"]
        HW[Hardware Pin / Sensor] --> Sensor[sovereign-sdk-sensor\nPoint-of-Genesis Micro-Signer]
    end

    subgraph Edge ["Edge Boundary"]
        Sensor -->|Signed Payload\nLoRaWAN / Serial| EdgeNode[sovereign-sdk-edge\nHMAC Verifier + Sieve]
        EdgeNode -->|Valid| Ledger[sovereign-sdk-ledger\nAppend-Only Local Log]
        EdgeNode -->|Invalid| Quarantine[.quarantine\nForensic Alert]
        EdgeNode -->|Ledger Down| Buffer[Durable JSONL\nOff-Grid Buffer]
        Buffer --> Staging[.staging\nRoll Recovery]
    end

    subgraph Outbound ["Outbound Boundary"]
        App[Local App / Coding Agent] --> Airlock[sovereign-sdk-airlock\nInline Proxy]
        Airlock --> Policy{Policy Gate}
        Policy -->|Block| Fault[Escalation Exception]
        Policy -->|Pass| Sieve[sovereign-sdk-sieve\nContext Minimization]
        Sieve --> API((Frontier Model API))
        Airlock --> Ledger
    end

    subgraph Vault ["Vault Boundary"]
        Memory[Ephemeral Memory] --> HSM[HSM / TPM\nHardware Seal]
        HSM --> Custody[Immutable\nOn-Disk Ciphertext]
        Custody --> Decay[Zero-Knowledge\nCryptographic Decay]
    end

    style Ingestion fill:#f5f5f5,stroke:#999
    style Edge fill:#e8f5e9,stroke:#388e3c
    style Outbound fill:#e3f2fd,stroke:#1976d2
    style Vault fill:#fff3e0,stroke:#f57c00

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    subgraph Ingestion ["Ingestion Boundary"]
        HW[Hardware Pin / Sensor] --> Sensor[sovereign-sdk-sensor\nPoint-of-Genesis Micro-Signer]
    end

    subgraph Edge ["Edge Boundary"]
        Sensor -->|Signed Payload\nLoRaWAN / Serial| EdgeNode[sovereign-sdk-edge\nHMAC Verifier + Sieve]
        EdgeNode -->|Valid| Ledger[sovereign-sdk-ledger\nAppend-Only Local Log]
        EdgeNode -->|Invalid| Quarantine[.quarantine\nForensic Alert]
        EdgeNode -->|Ledger Down| Buffer[Durable JSONL\nOff-Grid Buffer]
        Buffer --> Staging[.staging\nRoll Recovery]
    end

    subgraph Outbound ["Outbound Boundary"]
        App[Local App / Coding Agent] --> Airlock[sovereign-sdk-airlock\nInline Proxy]
        Airlock --> Policy{Policy Gate}
        Policy -->|Block| Fault[Escalation Exception]
        Policy -->|Pass| Sieve[sovereign-sdk-sieve\nContext Minimization]
        Sieve --> API((Frontier Model API))
        Airlock --> Ledger
    end

    subgraph Vault ["Vault Boundary"]
        Memory[Ephemeral Memory] --> HSM[HSM / TPM\nHardware Seal]
        HSM --> Custody[Immutable\nOn-Disk Ciphertext]
        Custody --> Decay[Zero-Knowledge\nCryptographic Decay]
    end

    style Ingestion fill:#f5f5f5,stroke:#999
    style Edge fill:#e8f5e9,stroke:#388e3c
    style Outbound fill:#e3f2fd,stroke:#1976d2
    style Vault fill:#fff3e0,stroke:#f57c00

Loading

Comments Outside Diff (3)

1. strategy/product_thesis.md, line 660-669 (link)

   Inconsistent component naming throughout docs

   strategy/product_thesis.md uses sovereign-sensor, sovereign-edge, sovereign-sieve, etc. (without the -sdk- infix), while strategy/commercial_strategy.md and strategy/roadmap.md use sovereign-sdk-sensor, sovereign-sdk-edge, etc. strategy/roadmap.md compounds the confusion by mixing both styles within the same document — Horizon 1 lists sovereign-sdk-sensor while Horizon 3 lists sovereign-vault (no -sdk- infix). Developers following these docs to install packages will encounter 404s or install the wrong package if the PyPI names don't match one canonical form.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

2. architecture/examples/museum/README.md, line 395 (link)

   Stray unresolved placeholder symbol

   The text reads "isolate raw structural metadata parameters (§) from prose descriptions" — the (§) appears to be an unresolved footnote or section-reference placeholder left over from an earlier draft. It reads as an artifact in the published documentation.

3. architecture/examples/warehouse/README.md, line 458-460 (link)

   sovereign-sdk-fastapi appears in prose but not in diagram or other examples

   The "Failure Moat" section names sovereign-sdk-fastapi as a deployment component, but it is absent from the Mermaid topology diagram above and does not appear in the equivalent section of the IoT, manufacturing, or museum blueprints. A reader consulting the diagram to understand the warehouse deployment will not see this component, creating a documentation gap that could cause misconfiguration.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

_{Reviews (1): Last reviewed commit: "docs(fix):" | Re-trigger Greptile}

[greptile-apps]

Diagram files are exact duplicates of embedded markdown diagrams

All four .mmd files (airlock_outbound.mmd, edge_pipeline.mmd, ingestion_boundary.mmd, vault_lifecycle.mmd) are character-for-character copies of the Mermaid code blocks already embedded in their corresponding .md files. Future updates must be applied in two places, and the two copies will inevitably drift. If these standalone files serve a specific build or rendering purpose (e.g., a documentation site that imports .mmd directly), that intent should be noted in a comment; otherwise, consider removing the duplicates and referencing the .md source of truth.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!