From 703a10bf0f8a45d1245f4ee78acfc58b70613fed Mon Sep 17 00:00:00 2001
From: gapview01 <107860548+gapview01@users.noreply.github.com>
Date: Sat, 30 Aug 2025 14:18:53 +1000
Subject: [PATCH] meta: scaffold front-door

---
 .github/workflows/ci.yml    | 15 +++++++++++++++
 ARCHITECTURE.md             | 21 +++++++++++++++++++++
 LICENSE                     |  2 +-
 README.md                   | 11 +++++++++--
 REPO-MAP.md                 | 22 ++++++++++++++++++++++
 docs/diagram-placeholder.md |  2 ++
 6 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 ARCHITECTURE.md
 create mode 100644 REPO-MAP.md
 create mode 100644 docs/diagram-placeholder.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..4e3e3cb
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,15 @@
+name: CI (lint-readme)
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+jobs:
+  readme-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check files exist
+        run: |
+          test -f README.md
+          test -f ARCHITECTURE.md
+          test -f REPO-MAP.md
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..e782a3b
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,21 @@
+# Architecture (4 Buckets)
+
+Goblin is organised into four conceptual buckets. Buckets are **meta categories**; the real units are the repos they group.
+
+1) **User, Developer & Agentic Experiences**
+   Wallet (web/mobile), Developer Console, first bot (tranched staking), agentic UX.
+
+2) **On-Chain Core (Solana)**
+   Anchor programs: Bot Factory, Master, Individual Bot; token configs; treasuries.
+
+3) **Off-Chain Smarts (platform-agnostic)**
+   API, Indexer, Timekeeper; SDK + CLI; CI/CD and observability. Cloud-agnostic.
+
+4) **Governance & Economics**
+   Treasury policy, upgrade/pause rules, tokenomics, future DAO.
+
+**Now vs Future**
+- Now: wallet, dev console, programs, services (API/indexer/timekeeper), SDK/CLI, first bot.
+- Future: more bots (added as separate repos), Swap, Stake UX, DAO.
+
+Principle: **Open where it builds trust. Private where it protects money.**
diff --git a/LICENSE b/LICENSE
index bc8755e..355b70e 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 gapview01
+Copyright (c) 2025 Goblin contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 9cd59f9..f0a3266 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,9 @@
-# goblin
-Goblin is a Solana agent wallet – more creature than app. It’s your entry to our modular ecosystem of bots, on‑chain programs, off‑chain services and governance. This repo maps the pieces and links you to the code.
+# Goblin — Solana Agent Wallet
+Not an app, a money creature.
+
+This is the **front door** to the Goblin ecosystem: a minimal map of what Goblin is, how it’s structured, and where to find the code.
+
+- Vision & layers: see **ARCHITECTURE.md**
+- Repos & links: see **REPO-MAP.md**
+
+We keep Goblin modular and open. Critical ops remain private.
diff --git a/REPO-MAP.md b/REPO-MAP.md
new file mode 100644
index 0000000..87f08cb
--- /dev/null
+++ b/REPO-MAP.md
@@ -0,0 +1,22 @@
+# Repository Map
+
+Buckets are conceptual; repos are the unit of analysis. Links are added as repos go live.
+
+## 1) User, Developer & Agentic Experiences (public)
+- goblin-wallet — Web/Mobile wallet
+- goblin-developer-console — Dev portal & control panel
+- goblin-bot-staking — First bot (tranched liquid staking)
+
+## 2) On-Chain Core (public)
+- goblin-programs — Anchor programs (Factory, Master, Bot)
+- goblin-tokens — Token metadata/configs
+
+## 3) Off-Chain Smarts (public/private)
+- goblin-services — API, Indexer, Timekeeper (logic only)
+- goblin-sdk — Client SDK
+- goblin-cli — CLI tools
+- goblin-infra — *(private)* IaC, pipelines, secrets
+
+## 4) Governance & Economics
+- goblin-dao — *(public scaffold)* future DAO/contracts/UI
+- goblin-governance-private — *(private)* treasury policy, tokenomics, governance docs
diff --git a/docs/diagram-placeholder.md b/docs/diagram-placeholder.md
new file mode 100644
index 0000000..41bb326
--- /dev/null
+++ b/docs/diagram-placeholder.md
@@ -0,0 +1,2 @@
+# Diagram Placeholder
+A simple diagram of the 4 buckets and satellites will live here. Keep the front door minimal.