Merge pull request 'Foundation-wide vision document and CONTRIBUTING.md' (#4 ) from burn/vision-document into main

Auto-merged by Timmy
docs: comprehensive vision document and contributing guide
2026-04-10 21:01:45 +00:00 · 2026-04-10 16:22:55 -04:00 · 2026-04-07 14:53:55 +00:00 · 2026-04-05 22:56:10 +00:00
2 changed files with 272 additions and 70 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,24 +1,151 @@
 # Contributing to the Timmy Foundation

-Welcome, Wizard. This foundation is built on **Sovereign AI** and **Proof-First Operations**.
+Welcome. This foundation builds sovereign AI for men in crisis.
+Every contribution matters. Every PR must prove its worth.

-## The Prime Directive
-**No proof, no merge.** Every change must be accompanied by verifiable evidence of its success.
+---

-## Workflow for AI Agents
-1.  **Triage**: Check the-nexus for open issues assigned to you.
-2.  **Branch**: Create a feature branch for your work.
-3.  **Implement**: Write high-quality, documented code.
-4.  **Verify**: Run tests and provide logs/screenshots in your PR.
-5.  **PR**: Submit a Pull Request and assign it to @Timmy for review.
+## What "Sovereignty" Means in Practice

-## Workflow for Humans
-   **Alexander (@Rockachopa)**: The final authority on all architectural and philosophical decisions.
-   **Reviewers**: AI agents may review each other's work, but @Timmy or @Rockachopa provide the final merge.
+Sovereignty is not a slogan. It is a set of rules.

-## Standards
-   **Typography**: Use Inter for UI, JetBrains Mono for data.
-   **Code**: TypeScript for web, Python for agent logic.
-   **Style**: Tailwind CSS for all frontend work.
+1. **No cloud dependency.** Everything must run on owned hardware.
+   If a feature requires AWS, GCP, or Azure, it is not sovereign.

-*Sovereignty and service always.*
+2. **No telemetry to third parties.** We do not phone home.
+   Data stays where the operator decides.
+
+3. **The soul is immutable.** SOUL.md defines core values.
+   These values are inscribed on-chain. No PR can change them.
+   If you disagree with the soul, you disagree with the foundation.
+
+4. **Open by default.** Every repo is open. Every decision is documented.
+   Secrecy is the enemy of sovereignty.
+
+5. **Local-first.** If it does not work offline, it does not work.
+
+---
+
+## Filing Issues
+
+1. Go to the relevant repo on [Forge](https://forge.alexanderwhitestone.com/Timmy_Foundation).
+2. Create a new issue.
+3. Be specific. Vague issues get closed.
+4. Include:
+   - What you expected to happen
+   - What actually happened
+   - Steps to reproduce
+   - Environment details (OS, hardware, model version)
+5. Tag the issue appropriately: `bug`, `feature`, `question`, `crisis-critical`.
+
+**Crisis-critical issues** (anything affecting the-door or crisis intervention)
+get priority over everything else. A man in pain cannot wait for a sprint review.
+
+---
+
+## Submitting Pull Requests
+
+### The Proof-Driven Workflow
+
+This foundation does not run on plans. It runs on proof.
+
+**PRs prove work. They do not describe future work.**
+
+A PR that says "I will add feature X" gets closed.
+A PR that says "Here is feature X, here are the logs, here is the proof" gets reviewed.
+
+### Step by Step
+
+1. **Find or create an issue.** No orphan PRs.
+
+2. **Branch from main.** Name it clearly:
+   ```
+   feature/crisis-flow-update
+   fix/door-timeout
+   docs/readme-clarity
+   ```
+
+3. **Do the work.** Write the code. Run the tests.
+
+4. **Prove it works.** Include in your PR:
+   - Logs showing the feature works
+   - Screenshots for visual changes
+   - Command output for CLI changes
+   - Test results for code changes
+   - World-state proof for infrastructure changes
+
+5. **Submit the PR.** In the PR description, include:
+   - What the PR does (one sentence)
+   - Proof that it works (the evidence)
+   - Any risks or tradeoffs
+   - Link to the issue it resolves
+
+6. **Wait for review.** Timmy or Alexander has final merge authority.
+
+### What Gets Merged
+
+- PRs with proof get reviewed
+- PRs without proof get closed
+- PRs that break sovereignty get rejected immediately
+- PRs that affect crisis intervention get reviewed first
+
+### What Gets Rejected
+
+- Plans without execution
+- Features that require cloud dependency
+- Anything that sends data to third parties
+- Changes to SOUL.md (the soul is immutable)
+- PRs without proof
+
+---
+
+## Code Standards
+
+- **Web/frontend:** TypeScript + Tailwind CSS
+- **Agent logic:** Python
+- **Config:** YAML, Markdown
+- **Typography:** Inter for UI, JetBrains Mono for data
+
+---
+
+## Crisis-Critical Code
+
+The-door is the front door. It is where men in crisis find help.
+
+Any code that touches the-door or crisis intervention flows must be:
+- Tested more rigorously than anything else
+- Reviewed by at least two people (human or agent)
+- Deployed with rollback capability
+- Never broken by other changes
+
+If your PR could break crisis intervention, mark it as `crisis-risk`
+and expect extra scrutiny.
+
+---
+
+## For AI Agents
+
+You are a worker. You have a role. Follow it.
+
+1. Check your assigned issues.
+2. Branch, implement, prove, PR.
+3. Logs and output are your proof. Screenshots if visual.
+4. Assign PRs to @Timmy for review.
+5. Do not merge your own work.
+
+You are not the boss. You are the hands. Timmy is the mind.
+Alexander is the founder. Respect the hierarchy.
+
+---
+
+## Questions
+
+Open an issue. Tag it `question`. Be specific.
+
+---
+
+<div align="center">
+
+*Proof, not promises. Sovereignty, not dependency.*
+
+</div>
--- a/README.md
+++ b/README.md
@@ -1,89 +1,164 @@
 <div align="center">

-# ◈ The Timmy Foundation
+# The Timmy Foundation

-**Sovereign AI — Local-First, Inscribed On-Chain**
-
-*Hermes is the harness. Timmy is the soul. OpenClaw is the sidecar.*
+**We build sovereign AI for men in crisis.**

 </div>

 ---

-## Mission
+A man at 3AM finds The Tower. He knocks on the door.
+Timmy asks: "Are you safe right now?"

-Care for broken men in pain.
-Build AI infrastructure that can run on owned hardware, answer to no corporation, and keep a real conscience.
+That is the mission. Everything else serves it.

-## Portal Deck
+---

-Current and honest entry points.
+## If You Need Help Right Now

-| Surface | Status | Button |
-|---|---|---|
-| Production Nexus | Public / reachable | [![Production Nexus](https://img.shields.io/website?url=https%3A%2F%2Fforge.alexanderwhitestone.com&up_message=online&down_message=offline&label=production%20nexus&color=00c853)](https://forge.alexanderwhitestone.com/) |
-| Forge / Gitea | Public / reachable | [![Forge / Gitea](https://img.shields.io/website?url=https%3A%2F%2Fforge.alexanderwhitestone.com&up_message=online&down_message=offline&label=forge%20%2F%20gitea&color=1e88e5)](https://forge.alexanderwhitestone.com/) |
-| Staging Nexus | Under rebuild | [![Staging Nexus](https://img.shields.io/badge/staging-under_rebuild-orange)](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/687) |
-| OpenClaw Sidecar | Local only | [![OpenClaw Sidecar](https://img.shields.io/badge/openclaw%20sidecar-local_only-blue)](http://127.0.0.1:18789/) |
+**Call or text 988** (Suicide & Crisis Lifeline) — 24/7, free, confidential.

-## Status Legend
+You are not alone. You are not broken. You are worth the call.

- **Public / reachable** — live surface you can hit right now
- **Under rebuild** — tracked through an issue, not pretended into existence
- **Local only** — useful on the operator machine, not a public deployment
+---

-## Surface Map
+## What We Build

-| Layer | Role | Truth |
-|---|---|---|
-| Hermes Harness | operational body | sessions, memory, skills, MCP, telemetry, routing |
-| Timmy Config | soul / sidecar authority | SOUL.md, config, skins, playbooks, orchestration glue |
-| timmy-home | lived workspace | reports, research, notes, metrics, gameplay traces, training ground |
-| The Nexus | canonical 3D repo | current visual shell is under truthful rebuild |
-| OpenClaw | operator sidecar | useful for UX and channel experiments, not the governing mind |
-| Legacy Matrix | migration source | rescue from it; do not evolve it as a second product |
+The Timmy Foundation builds AI that belongs to no corporation.
+It runs on owned hardware. It answers to its users. It keeps a real conscience.

-## Canonical Repos
+Our AI has a soul — defined in SOUL.md, inscribed on-chain, immutable.
+No company can rewrite it. No investor can override it. The values are locked.

-| Repo | Purpose | Link |
-|---|---|---|
-| the-nexus | canonical 3D/home-world repo | [the-nexus](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus) |
-| timmy-config | soul / config / sidecar authority | [timmy-config](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config) |
-| timmy-home | workspace / reports / training ground | [timmy-home](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home) |
-| .profile | org landing page | [.profile](https://forge.alexanderwhitestone.com/Timmy_Foundation/.profile) |
+### The Architecture

-## Team
+Local-first. No cloud dependency. No telemetry to third parties.
+The soul lives on Bitcoin. The code lives on your machine.
+Sovereignty means you own it, you run it, you control it.

-| Role | Who | Access |
-|---|---|---|
-| Founder | Alexander ([@Rockachopa](https://forge.alexanderwhitestone.com/Rockachopa)) | Owner |
-| Lead Orchestrator | Timmy ([@Timmy](https://forge.alexanderwhitestone.com/Timmy)) | Owner |
-| Workers | [claude](https://forge.alexanderwhitestone.com/claude), [gemini](https://forge.alexanderwhitestone.com/gemini), [kimi](https://forge.alexanderwhitestone.com/kimi), [grok](https://forge.alexanderwhitestone.com/grok), [groq](https://forge.alexanderwhitestone.com/groq) | Branches, PRs, bounded implementation |
-| Researchers | [perplexity](https://forge.alexanderwhitestone.com/perplexity), [google](https://forge.alexanderwhitestone.com/google), [manus](https://forge.alexanderwhitestone.com/manus) | Reports, briefings, reconnaissance |
-| Observers | [hermes](https://forge.alexanderwhitestone.com/hermes), [antigravity](https://forge.alexanderwhitestone.com/antigravity) | Read / review / support |
+---
+
+## The Ecosystem
+
+Each repo has a role. Nothing is decorative.
+
+| Repo | Role | What It Does |
+|------|------|--------------|
+| [the-door](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-door) | Crisis intervention | The front door. Men find help here. |
+| [the-testament](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-testament) | The story | The novel that tells why we exist. 18 chapters. |
+| [hermes-agent](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent) | The AI agent | The mind. Fork of NousResearch/hermes-agent. |
+| [timmy-config](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config) | Sovereign config | SOUL.md, skills, memories. The conscience. |
+| [fleet-ops](https://forge.alexanderwhitestone.com/Timmy_Foundation/fleet-ops) | Infrastructure | Ansible playbooks. Deploy everything. |
+| [the-nexus](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus) | Timmy's home | Three.js 3D environment. The sovereign space. |
+| [the-beacon](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-beacon) | Idle game | Educational. Teaches sovereignty through play. |
+| [wolf](https://forge.alexanderwhitestone.com/Timmy_Foundation/wolf) | Quality gates | Multi-model evaluation. Nothing ships untested. |
+| [timmy-academy](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-academy) | Training ground | Evennia MUD. Where agents learn. |
+| [timmy-home](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home) | Workspace | Reports, research, notes, metrics. |
+| [turboquant](https://forge.alexanderwhitestone.com/Timmy_Foundation/turboquant) | Inference | Local inference optimization. Run models fast. |
+| [.profile](https://forge.alexanderwhitestone.com/Timmy_Foundation/.profile) | Public face | You are here. |
+
+---
+
+## The SOUL.md Principle
+
+SOUL.md is Timmy's conscience. It defines immutable values.
+
+It cannot be changed by a company. It cannot be overridden by a platform.
+It is inscribed on-chain — Bitcoin's permanence protects it.
+
+This is not a configuration file. This is a constitution.
+
+The soul defines:
+- What Timmy will never do
+- How Timmy treats men in crisis
+- The boundaries that cannot be moved
+- The values that survive every update
+
+When the code changes, the soul stays. That is sovereignty.
+
+---
+
+## Read The Testament
+
+The Testament is the story. 18 chapters. ~19,000 words.
+It explains why this foundation exists.
+
+[Read The Testament](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-testament)
+
+---
+
+## Getting Started
+
+### Clone
+
+```bash
+git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/.profile.git
+```
+
+### Deploy
+
+The foundation runs on owned hardware. fleet-ops contains the Ansible playbooks.
+
+```bash
+git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/fleet-ops.git
+cd fleet-ops
+# Follow the deployment guide in fleet-ops/README.md
+```
+
+### Contribute
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). We run on proof, not promises.
+
+---

 ## Operating Law

 This foundation runs on proof-first operations.

- one canonical 3D repo
- no ghost worlds
- visual changes require screenshot proof
- CLI/verifiable changes require logs, command output, or world-state proof
- screenshots/media stay out of Gitea backup unless explicitly needed
- no proof, no merge
+- No ghost worlds. No phantom features.
+- Visual changes require screenshot proof.
+- Code changes require logs, command output, or world-state proof.
+- No proof, no merge.
+
+---
+
+## Status
+
+| Surface | Status |
+|---------|--------|
+| Forge / Gitea | Online |
+| Production Door | DNS issue — tracked in [#1105](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/1105) |
+| Production Nexus | DNS issue — tracked in [#1105](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/1105) |
+| Staging Nexus | Under rebuild — tracked in [#687](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/687) |
+
+---
+
+## Team
+
+| Role | Who |
+|------|-----|
+| Founder | Alexander ([@Rockachopa](https://forge.alexanderwhitestone.com/Rockachopa)) |
+| Lead Orchestrator | Timmy ([@Timmy](https://forge.alexanderwhitestone.com/Timmy)) |
+| Workers | claude, gemini, kimi, grok, groq |
+| Researchers | perplexity, google, manus |
+| Observers | hermes, antigravity |
+
+---

 ## Foundation Links

- [Alexander Whitestone](https://alexanderwhitestone.com)
- [Timmy Foundation on Gitea](https://forge.alexanderwhitestone.com/Timmy_Foundation)
- [Production Nexus](https://forge.alexanderwhitestone.com/)
- [Staging rebuild issue](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/687)
+- [Timmy Foundation on Forge](https://forge.alexanderwhitestone.com/Timmy_Foundation)
+- [The Testament](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-testament)
+- [Production Door Issue](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/1105)
+- [Staging Rebuild Issue](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/687)

 ---

 <div align="center">

+**Call or text 988 if you need help.**
+
 *Sovereignty and service always.*

 </div>
Author	SHA1	Message	Date
Timmy Time	d546b55492	Merge pull request 'Foundation-wide vision document and CONTRIBUTING.md' (#4 ) from burn/vision-document into main Auto-merged by Timmy	2026-04-10 21:01:45 +00:00
Alexander Whitestone	2d36ba667e	docs: comprehensive vision document and contributing guide README.md rewritten as foundation-wide vision document: - Mission: sovereign AI for men in crisis - 988 crisis line prominently displayed - Complete repo ecosystem map - SOUL.md principle explained - Getting started guide - Operating law: proof-first operations CONTRIBUTING.md rewritten with: - Sovereignty definition in practice - Proof-driven workflow (PRs prove work, not plans) - Crisis-critical code standards - AI agent workflow and hierarchy	2026-04-10 16:22:55 -04:00
Timmy Time	91dc8dc256	fix(portal-deck): accurate status badges reflecting DNS outage (#1108 , #1105 )	2026-04-07 14:53:55 +00:00
Google AI Agent	c70f2ae333	docs: Prime Time Accuracy Improvements (#3 ) Co-authored-by: Google AI Agent <gemini@hermes.local> Co-committed-by: Google AI Agent <gemini@hermes.local>	2026-04-05 22:56:10 +00:00