HEAV3NS-PRESS

"Dismantle the category. Eliminate the plugins. Deploy, entrust with your content, and walk away."

In one sentence: HEAV3NS-PRESS is an aggressively compact, self-governing publishing infrastructure written in Rust that operates autonomously without requiring permanent human administration.

---

---

Table of Contents

• The Idea in 60 Seconds
• Why this exists (The Category Distillation)
• Architectural Mandate & Invariants
• For AI Agents & Model Context Protocol
• Quick Start (Under 2 Minutes)
• Five Zones at a Glance
• CLI Reference
• HTTP Endpoints & Syndication
• Self-Healing & Proof-Before-Mutation
• Documentation Architecture (Diátaxis + Institutional Memory)
• The Five Questions Every Agent Must Answer
• 60-Second Quick Reference Card
• Contributing, Security & License

---

The Idea in 60 Seconds

Dimension	Specification
What	A single, zero-external-dependency Rust publishing binary with built-in Content-Addressable Storage (CAS), crash-resilient WAL, Axum HTTP engine, and autonomous supervisor daemon.
Why	Traditional CMS platforms (e.g. WordPress, Ghost) require perpetual human gardening: updating fragile plugins, running database migrations, vacuuming SQL tables, and babysitting dependencies.
How	Built under Deploy-and-Abandon: the system independently validates host resources, schedules posts, detects bitrot, rolls back to intact revisions, isolates corrupt records to quarantine, and seals Merkle backups.
Agent-Native	Native stdio Model Context Protocol (MCP 2024-11-05) server, 100% CLI --json parity, /llms.txt, and /.well-known/agent.json.
Cost	Single binary, zero external SQL daemons (no MySQL/Postgres), 0% I/O in domain logic, and sub-millisecond startup.

---

Why this exists (The Category Distillation)

For three decades, web publishing software was built around an administrative trap:

• Web servers, script runtimes, SQL databases, cron jobs, and third-party plugin marketplaces were cobbled together into fragile monoliths.
• Every installed plugin introduced security attack vectors and maintenance obligations.
• If left unattended for six months, the system broke.

HEAV3NS-PRESS dismantles the category.

• Zero plugins: Publishing, Markdown conversion, Atom/RSS syndication, XML sitemaps, full-text search, and Prometheus telemetry are built directly into the core engine.
• Zero SQL database servers: State is maintained in-process through an append-only Write-Ahead Log (WAL), atomic JSON snapshots, and sharded SHA-256 CAS blobs.
• Zero administrative toil: An autonomous supervisor loop maintains system health, self-heals corrupted records, and manages backups continuously.

---

Architectural Mandate & Invariants

flowchart TD
  subgraph UI ["UI Layer (src/ui/ & src/main.rs)"]
    CLI["CLI Engine (18 Commands)"]
    HTTP["Axum Web Server (30 Routes)"]
    MCP["Stdio MCP Server (18 Tools)"]
  end

  subgraph CORE ["Core Layer (src/core/)"]
    ENG["AutonomousEngine (Supervisor Loop)"]
    CS["ContentService (CRUD & Revisions)"]
    HEAL["SelfHealingCoordinator (Reconciliation)"]
    PRES["PreservationEngine (Backups & Exports)"]
    JOY["JoyRideCache (Bounded Ergonomics Cache)"]
    BQ["BroccoliQueueEngine (Job Processor)"]
  end

  subgraph DOMAIN ["Domain Layer (src/domain/ — 0% I/O)"]
    MODELS["ContentItem & ContentRevision"]
    POL["PublishingPolicy & RetentionPolicy"]
    SUB["JoyRideKind & JobRecord State Machine"]
    TRAITS["Trait Contracts (IContentStore, IJoyRideCache, IJobQueue, ...)"]
  end

  subgraph INFRA ["Infrastructure Layer (src/infrastructure/)"]
    FILE["FileContentStore (WAL + items.json)"]
    CAS["CasStore (Sharded SHA-256 Blobs)"]
    BKUP["BackupManager (Merkle Trees)"]
    RECON["StateReconciler (Quarantine Ledger)"]
    INSP["SysInspector (Host Resources)"]
  end

  subgraph PLUMB ["Plumbing Layer (src/plumbing/)"]
    HASH["SHA-256 & Merkle Primitives"]
    SLUG["Slugify & Regex Validator"]
    TIME["ISO-8601 UTC Utilities"]
    MD["Markdown-to-HTML Parser"]
  end

  UI --> CORE
  CORE --> DOMAIN
  INFRA -.->|implements| TRAITS
  CORE --> TRAITS
  INFRA --> PLUMB
  CORE --> PLUMB

Loading

• 0% I/O in DOMAIN: Pure models, validation policies, and state transitions. Never imports file system or network crates.
• Contractual Sovereignty (I<Name>): CORE orchestrators bind exclusively to formal trait contracts in src/domain/interfaces/.
• Proof-Before-Mutation: State reconciliation follows strict proof (Audit -> Diagnosis -> Execution -> Post-Verification).
• Never Silently Destroy: Irrecoverable corrupt payloads are preserved in quarantine with raw forensic evidence intact.

---

For AI Agents & Model Context Protocol

HEAV3NS-PRESS includes a native Model Context Protocol (MCP 2024-11-05) stdio server. AI coding agents (Claude Desktop, Cursor, Antigravity, Windsurf) connect directly without writing shell wrappers:

heav3ns-press mcp --dir .heav3ns

Claude Desktop Setup (claude_desktop_config.json):

{
  "mcpServers": {
    "heav3ns-press": {
      "command": "/usr/local/bin/heav3ns-press",
      "args": ["mcp", "--dir", "/var/lib/heav3ns"]
    }
  }
}

Exposed Tools:

• publish_post: Create, update, publish, or schedule articles.
• get_post: Retrieve full post metadata, markdown body, and SHA-256 hash.
• list_posts: Filter articles by status (published, draft, scheduled, archived).
• search_posts: Full-text search across content.
• inspect_health: Inspect real-time component health and host disk telemetry.
• run_self_healing: Force immediate state reconciliation and repair.
• create_backup: Generate an atomic, verified Merkle snapshot.
• rollback_revision: Atomically restore an article to a prior revision number.

See docs/MCP_GUIDE.md for full configuration.

---

Quick Start (Under 2 Minutes)

# 1. Build release binary
cargo build --release

# 2. Bootstrap publishing root
./target/release/heav3ns-press init --dir .heav3ns

# 3. Publish an article
./target/release/heav3ns-press publish "Hello Autonomous World" \
  --slug "hello-autonomous-world" \
  --body "# Welcome\nPublishing infrastructure that runs itself." \
  --tags "welcome,tech" \
  --dir .heav3ns

# 4. Launch autonomous server
./target/release/heav3ns-press serve --port 8080 --dir .heav3ns

Open http://127.0.0.1:8080 in your browser.

---

Five Zones at a Glance

Zone	Directory	Responsibility	Invariant
DOMAIN	src/domain/	Pure business models, lifecycle state, policies, interface traits	0% I/O. Never import filesystem or network crates.
CORE	src/core/	Application orchestrators: supervisor loop, self-healing, content service	Coordinates domain and infrastructure via traits. Never imports ui.
INFRASTRUCTURE	src/infrastructure/	Concrete adapters: WAL store, sharded CAS, backup manager, sys inspector	Implements domain traits. Never imports ui.
PLUMBING	src/plumbing/	Stateless helpers: SHA-256 hash, Merkle root, slugify, time, markdown	Pure leaf primitives. Zero upward imports.
UI	src/ui/, src/main.rs	CLI entrypoints, Axum HTTP routes, Stdio MCP server, presenters	Presentation and routing. Composition root wires adapters.

---

CLI Reference

All 18 commands support the global --json flag for deterministic, machine-readable output:

Command	Description
heav3ns-press init	Bootstraps configuration, shard directories, and welcome article
heav3ns-press serve	Launches HTTP server and autonomous supervisor daemon
heav3ns-press status	Quick status report (health, items, storage, uptime)
heav3ns-press publish	Publishes or schedules an article from arguments or markdown file
heav3ns-press list	Lists published, draft, or scheduled articles
heav3ns-press get <slug>	Retrieves article metadata, revision history, and markdown body
heav3ns-press search <q>	Full-text keyword search across published content
heav3ns-press revisions <slug>	Inspects immutable version history and cryptographic hashes
heav3ns-press rollback <slug> <v>	Atomically rolls back an article to a prior revision number
heav3ns-press doctor	Runs deep health, writeability, and disk checks
heav3ns-press heal	Triggers immediate self-healing state reconciliation
heav3ns-press backup	Creates a verified Merkle backup snapshot (--list, --restore <id>)
heav3ns-press quarantine	Inspects and resolves isolated corrupt records (list, inspect, resolve)
heav3ns-press export <dir>	Exports content to portable Markdown with YAML frontmatter
heav3ns-press import <dir>	Imports portable Markdown directory
heav3ns-press tick	Runs a single autonomous operational cycle (for cron or serverless)
heav3ns-press cache	Inspects, clears, or runs memory pressure on JoyRide cache
heav3ns-press queue	Inspects, lists, enqueues, claims, or purges BroccoliQueue jobs
heav3ns-press mcp	Starts Model Context Protocol (MCP 2024-11-05) stdio server

See docs/api/cli.md for full argument flags.

---

HTTP Endpoints & Syndication

Route	Method	Purpose
/	GET	Responsive HTML homepage (or JSON if Accept: application/json)
/posts/:slug	GET	Rendered post with estimated reading time
/search?q=...	GET	Full-text search HTML view and JSON API
/feed.atom, /feed.xml	GET	Atom 1.0 syndication feed
/feed.rss, /rss.xml	GET	RSS 2.0 syndication feed
/sitemap.xml	GET	XML Sitemap for search engines
/robots.txt	GET	Robots file referencing sitemaps and LLM manifest
/llms.txt	GET	Machine-readable LLM context manifest
/.well-known/agent.json	GET	Agent capability manifest and tool schema
/healthz	GET	Instant liveness check (200 OK)
/readyz	GET	Readiness probe (200 OK or 503 Service Unavailable)
/metrics	GET	Prometheus operational metrics
/diagnostics	GET	Detailed JSON health and disk diagnostics
/api/posts	GET, POST	Content management REST API
/api/posts/:slug	GET, PUT, DELETE	Individual content CRUD
/api/posts/:slug/rollback	POST	Time-travel rollback to target revision
/api/heal	POST	Trigger self-healing state reconciliation
/api/backup	GET, POST	List or create verified Merkle backups
/api/quarantine	GET	List isolated corrupt records
/api/cache/stats	GET	Real-time JoyRide cache telemetry & hit ratio
/api/cache/clear	POST	Purge JoyRide execution cache
/api/cache/invalidate	POST	Invalidate cache by key, prefix, or tag
/api/queue/stats	GET	BroccoliQueue active & pending job counts
/api/queue/jobs	GET	List queued background tasks
/api/queue/enqueue	POST	Enqueue background job with idempotency key
/api/queue/retry-all	POST	Bulk retry terminal Failed jobs
/api/queue/drain	POST	Drain and discard waiting jobs
/api/queue/progress	POST	Report worker task progress percentage
/dashboard	GET	Real-time HTML observability dashboard

---

Self-Healing & Proof-Before-Mutation

1. Crash Resilience: In-flight mutations are recorded in an append-only WAL. During restart after power failure, torn trailing writes are automatically identified and cleanly truncated (PM-001).
2. Bitrot Detection: Every content payload is checked against its expected SHA-256 CAS hash. If disk degradation occurs, the engine rolls back to the most recent intact historical revision (PM-002).
3. Zero Data Loss Isolation: If no intact revision exists, the record and raw disk bytes are preserved in the QuarantineLedger with full forensic evidence intact (ADR-0005).
4. Deterministic Merkle Backups: Backups are sealed with a binary Merkle tree root hash, enabling instant mathematical proof of integrity (ADR-0004).

---

Documentation Architecture (Diátaxis + Institutional Memory)

Full documentation lives in docs/, organized under the Diátaxis + Institutional Memory architecture:

docs/
├── README.md               # Documentation Hub & Reading Paths
├── DOCS_GUIDE.md           # Documentation Principles & Complete Taxonomy
├── AGENT_STACK.md          # Spatial Rules + Autonomous Substrate + Agent Tooling
├── CONSTITUTION.md         # The 6 Immutable Laws of HEAV3NS-PRESS
├── CODEBASE_STANDARDS.md   # Repository Layout, Zone Discipline, AI Rules
├── GETTING_STARTED.md      # 10-Minute Onboarding Tutorial
├── OPERATIONS.md           # Operator Runbook, Systemd, Telemetry, CLI
├── SECURITY_BEST_PRACTICES.md # Threat Model, CAS Integrity, Path Traversal
├── GLOSSARY.md             # Terms, Concepts, and Error Definitions
├── CI_INTEGRATION.md       # CI Pipeline & Pre-Commit Hook Guide
├── PROPAGATION.md          # Autonomous Deployment & Agent Prompts
├── RELEASING.md            # SemVer Rules & Release Checklist
├── MCP_GUIDE.md            # Native Model Context Protocol Reference
├── adr/                    # Architecture Decision Records (ADR-0001..0006 + Template)
├── playbooks/              # Operational Incident Playbooks (PB-01..05)
├── wiki/                   # Engineering Wiki (Mental Models, Rust Recipes, Metrics)
├── postmortems/            # Blameless SRE Postmortems (PM-001..005 + Template)
├── kb/                     # Knowledge Base (3-Tier Lifecycle, Symptom Matrix, FAQ)
├── papers/                 # Research Papers (Companion Brief, Philosophy, Whitepaper)
├── api/                    # Programmatic Rust API, CLI Reference, Error Catalog
└── architecture/           # System Architecture & State Reconciliation Pipeline

---

The Five Questions Every Agent Must Answer

Before completing any task on HEAV3NS-PRESS, an agent must verify:

1. Which zone does this file belong to? Declared via top-of-file [LAYER: <ZONE>] header.
2. Does the folder path match the zone? Verified by Principle of Geographic Alignment.
3. Is domain logic 100% pure? 0% I/O in src/domain/.
4. Do tests and linters pass cleanly? cargo fmt, cargo clippy, cargo test.
5. Does joy-check report zero blocking violations? PASS (SOVEREIGN) with 0 violations.

---

60-Second Quick Reference Card

# Full verification suite (tests, formatting, clippy, joy-check, docs-check)
./scripts/verify.sh

# Run only unit & integration tests
cargo test --all-targets

# Check Joyzoning sovereign architecture compliance
node /Users/bozoegg/Desktop/HEAV3NS-JOY/bin/joy-check.mjs .

# Check documentation guardrails and relative links
node ./scripts/docs-check.mjs .

# Start the autonomous daemon
heav3ns-press serve --port 8080 --dir .heav3ns

# Run Model Context Protocol stdio server
heav3ns-press mcp --dir .heav3ns

---

Contributing, Security & License

• Contributing: Review CONTRIBUTING.md for pull request workflows and Joyzoning guidelines.
• Code of Conduct: Review CODE_OF_CONDUCT.md.
• Security: Report vulnerabilities responsibly according to SECURITY.md.
• Support: See SUPPORT.md.
• Validation Report: See VALIDATION_REPORT.md.
• License: MIT License. See LICENSE.