From 851cd3277f03cf52bec903ec6b835d42d37f4ce1 Mon Sep 17 00:00:00 2001
From: Samuel James <samueljamesinc@gmail.com>
Date: Wed, 10 Jun 2026 12:38:31 +0000
Subject: [PATCH] init: project vision and architecture

---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 63 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 589f116..75d8041 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,64 @@
-# forge
+# Forge
+
+Where agents are built, shaped, and hardened.
+
+## Vision
+
+A hybrid automation platform: self-hosted orchestration (cron, bash, Ansible) calling AWS Bedrock for intelligence. No frameworks. No fragile plugin systems. Just scripts, prompts, and reliable execution.
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│          Trigger Layer              │
+│   cron · Ansible · webhook · CLI    │
+└──────────────────┬──────────────────┘
+                   │
+┌──────────────────▼──────────────────┐
+│          Agent Runtime              │
+│   SOUL.md + workflow prompt + curl  │
+│   → AWS Bedrock (Claude Haiku)     │
+└──────────────────┬──────────────────┘
+                   │
+┌──────────────────▼──────────────────┐
+│          Output Layer               │
+│   Trillium · Obsidian · Telegram   │
+│   S3 · logs                         │
+└─────────────────────────────────────┘
+```
+
+Each agent is a directory. Each workflow is a bash script + prompt file. Intelligence comes from Bedrock. Control stays with you.
+
+## Principles
+
+1. No dependencies beyond bash, curl, jq, and AWS CLI
+2. Every execution logged (input, output, tokens, cost)
+3. SOUL.md is the single source of personality
+4. Model-agnostic — swap Bedrock for Ollama with one env var
+5. Agents have boundaries — they do what they do and nothing else
+
+## Structure
+
+```
+forge/
+├── agents/
+│   └── scribe/          # Knowledge enhancer, writer, diagrammer
+├── automations/
+│   ├── cron/            # Scheduled tasks
+│   └── ansible/         # Infrastructure playbooks
+├── decisions/           # Architecture Decision Records
+└── README.md
+```
+
+## Cost
+
+Target: $2–15/month (Claude Haiku via Bedrock) for all agents combined.
+
+## Status
+
+- [x] Project created
+- [ ] Scribe SOUL.md finalized
+- [ ] Bedrock access configured
+- [ ] First workflow (enhance_notes) operational
+- [ ] Telegram gateway wired
 
-Automations and AI agents — built to last
\ No newline at end of file