diff --git a/network-poc/AGENTBUILDER.md b/network-poc/AGENTBUILDER.md
new file mode 100644
index 0000000..1b2fabf
--- /dev/null
+++ b/network-poc/AGENTBUILDER.md
@@ -0,0 +1,215 @@
+# Kipinä Agent Builder — Suunnitelma
+
+Käyttäjä voi rakentaa omia agentteja "hahmolomakkeella": valitsee avatarin, roolin, kielimallin ja muokkaa prompteja. Agentit tallentuvat localStorageen ja ovat käytettävissä pipelineissa.
+
+## Nykytila
+
+```js
+// Kovakoodattu agentPrompts-objekti
+const agentPrompts = {
+    manager: { name: 'Manageri', model: 'qwen2.5-coder:7b', default: '...' },
+    coder:   { name: 'Koodari', model: 'qwen2.5-coder:7b', default: '...' },
+    tofuist: { name: 'Tofuist', model: 'qwen2.5-coder:7b', docs: '/docs/tofu-cheatsheet.md', default: '...' },
+    // ...
+};
+```
+
+**Ongelma:** Uuden agentin lisääminen vaatii koodimuutoksen index.html:ään.
+
+## Tavoite
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Agent Builder -lomake                              │
+│                                                     │
+│  ┌─────────┐  Nimi: [Tofuist          ]             │
+│  │ 🦎      │  Rooli: [IaC / Infra    ▼]            │
+│  │ avatar  │  Malli: [qwen2.5-coder:7b ▼]          │
+│  └─────────┘  Docs:  [/docs/tofu-cheatsheet.md]    │
+│                                                     │
+│  System Prompt:                                     │
+│  ┌─────────────────────────────────────────────┐    │
+│  │ You are an OpenTofu/Terraform IaC specialist│    │
+│  │ ...                                         │    │
+│  └─────────────────────────────────────────────┘    │
+│                                                     │
+│  LLM-parametrit:                                    │
+│  Temperature: [0.7]  Top-k: [40]  Max tokens: [512]│
+│                                                     │
+│  [💾 Tallenna]  [🗑️ Poista]  [📤 Export JSON]       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Building Blocks
+
+### 1. Agenttiskeema
+
+```js
+{
+    id: 'tofuist',                          // uniikki tunniste
+    name: 'Tofuist',                        // näyttönimi
+    avatar: '/avatars/gecko_notext.png',     // avatar-kuvan polku
+    role: 'iac',                             // rooli-template
+    model: 'qwen2.5-coder:7b',             // eksakti Ollama-mallinimi
+    color: '#e3a336',                        // teemaväri UI:ssa
+    docs: '/docs/tofu-cheatsheet.md',        // valinnainen referenssidokumentti
+    prompt: 'You are an OpenTofu...',        // system prompt
+    params: {                                // LLM-parametrit
+        temperature: 0.7,
+        top_k: 40,
+        max_tokens: 512,
+        repetition_penalty: 1.15
+    }
+}
+```
+
+### 2. Rooli-templatet (alasvetovalikko)
+
+Valmiit pohjat jotka tuovat oletuspromptit ja parametrit:
+
+| Rooli | Oletusprompt | Parametrit |
+|-------|-------------|------------|
+| Koodari | "Kirjoita selkeää, testattavaa koodia" | temp 0.7, max 512 |
+| QA / Testaus | "Kirjoita testejä, etsi virheitä" | temp 0.4, max 512 |
+| DevOps | "Dockerfile, Compose, CI/CD" | temp 0.5, max 512 |
+| DevSecOps | "Tietoturva-auditointi, OWASP" | temp 0.3, max 512 |
+| Arkkitehti | "Järjestelmäsuunnittelu, rajapinnat" | temp 0.6, max 512 |
+| IaC / Infra | "OpenTofu/Terraform HCL-koodi" | temp 0.5, max 512 |
+| Data | "Tietokannat, SQL, datamallit" | temp 0.5, max 512 |
+| Manageri | "Tehtävien jako ja koordinointi" | temp 0.8, max 200 |
+| Kirjoittaja | "Dokumentaatio, README, ohjeet" | temp 0.8, max 512 |
+| Vapaa | (tyhjä, käyttäjä kirjoittaa) | temp 0.7, max 512 |
+
+### 3. Malli-valitsin
+
+Lista saatavilla olevista malleista — haetaan dynaamisesti:
+
+```
+Hub-kysely: GET /api/models → palauttaa yhdistettyjen solmujen mallit
+
+Tai staattinen lista:
+- qwen2.5-coder:7b    (oletus, natiivi GPU)
+- qwen2.5-coder:1.5b  (kevyt)
+- qwen2.5-coder:0.5b  (selain Wasm)
+- deepseek-r1          (reasoning)
+- llama3.2:3b          (yleiskäyttö)
+```
+
+Pitkän aikavälin tavoite: hub ilmoittaa WebSocketin kautta mitkä mallit ovat saatavilla.
+
+### 4. Avatar-valitsin
+
+Valmiit avatarit + mahdollisuus ladata oma:
+
+| Hahmo | Tiedosto | Eläin |
+|-------|----------|-------|
+| Asiakas | kettu_notext.png | Kettu |
+| Manageri | karhunpentu.png | Karhunpentu |
+| Koodari | kipina_notext.png | Salamanteri |
+| Data | pesukarhu_notext.png | Pesukarhu |
+| QA | susi_notext.png | Pikkususi |
+| DevOps | laiskiainen_notext.png | Laiskiainen |
+| Tarkkailija | aikuinen_susi.png | Aikuinen susi |
+| Tofuist | gecko_notext.png | Gecko/Lisko |
+| Arkkitehti | ??? | (tulossa) |
+| DevSecOps | ??? | (tulossa) |
+
+### 5. Docs-kenttä (referenssidokumentti)
+
+Agentti voi viitata ulkoiseen dokumenttiin joka ladataan promptiin:
+
+```
+docs: '/docs/tofu-cheatsheet.md'  →  haetaan fetch():llä, cachetetaan _docsCache-kenttään
+```
+
+**Toiminta:**
+1. Ensimmäisellä `kpnRun`-kutsulla ladataan docs-URL
+2. Sisältö cachetetaan `agent._docsCache`-kenttään
+3. Liitetään promptiin: `"Reference:\n" + docsContent`
+4. Ei ladata uudelleen saman session aikana
+
+**Rajoitukset:**
+- Max ~3000 tokenia (~10 KB) — pidempi docs tiivistetään
+- Vain tekstitiedostot (.md, .txt)
+
+### 6. Tallennus (localStorage)
+
+```js
+// Tallennusavain
+'kpn-custom-agents' → JSON.stringify([ agentSkeema1, agentSkeema2, ... ])
+
+// Ladattaessa
+const customAgents = JSON.parse(localStorage.getItem('kpn-custom-agents') || '[]');
+const defaultAgents = { manager: {...}, coder: {...}, ... };
+const agentPrompts = { ...defaultAgents };
+for (const agent of customAgents) {
+    agentPrompts[agent.id] = agent;
+}
+```
+
+**Oletusagentit** (manager, coder, tester, qa, data) ovat aina mukana — niitä ei voi poistaa, mutta prompteja voi muokata.
+
+**Käyttäjäagentit** (tofuist, arkkitehti, devsecops, ...) tallentuvat localStorageen ja latautuvat käynnistyksessä.
+
+### 7. Export / Import
+
+```js
+// Export — JSON-tiedosto
+const blob = new Blob([JSON.stringify(agent, null, 2)], { type: 'application/json' });
+// → agent-tofuist.json
+
+// Import — tiedoston valinta tai drag & drop
+// Validoidaan skeema, lisätään agentPrompts-objektiin
+```
+
+Mahdollistaa agenttien jakamisen tiimin kesken.
+
+## Toteutusvaiheet
+
+### Vaihe 1: Hahmolomake UI
+- Avatar-grid valitsin
+- Rooli-template alasvetovalikko (täyttää oletuspromptit)
+- Malli-valitsin
+- System prompt -tekstikenttä
+- LLM-parametrit (temperature, top-k, max_tokens)
+- Tallenna/Poista-napit
+
+### Vaihe 2: Dynaaminen agenttirekisteri
+- `agentPrompts` ladataan localStoragesta
+- Oletusagentit + käyttäjän agentit yhdistetään
+- Avatar-kortit renderöidään dynaamisesti (ei HTML:ssä)
+- Värimapit generoidaan agenttiskeemasta
+
+### Vaihe 3: Pipeline käyttää dynaamisia agentteja
+- Pipeline-vaiheet viittaavat agentin id:hen (ei kovakoodattuun nimeen)
+- Käyttäjä voi valita mitkä agentit osallistuvat pipelineen
+- Tofuist voi korvata DevOpsin IaC-projekteissa
+
+### Vaihe 4: Mallirekisteri (hub-integraatio)
+- Hub tarjoaa `/api/models`-endpointin
+- Saatavilla olevat mallit näkyvät valitsimessa reaaliajassa
+- Solmun liittyessä/poistuessa mallit päivittyvät
+
+## Arkkitehtuurikaavio
+
+```
+┌──────────────────────────────────────────────────┐
+│  Agent Builder UI                                │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │ Avatar   │ │ Rooli    │ │ Malli-valitsin   │  │
+│  │ Grid     │ │ Template │ │ (hub/staattinen) │  │
+│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘  │
+│       └─────────────┼───────────────┘             │
+│                     ▼                             │
+│  ┌──────────────────────────────────────────────┐ │
+│  │  Agent Schema  { id, name, avatar, model,   │ │
+│  │                  role, color, docs, prompt,  │ │
+│  │                  params }                    │ │
+│  └──────────────────┬───────────────────────────┘ │
+│                     │                             │
+│       ┌─────────────┼─────────────┐               │
+│       ▼             ▼             ▼               │
+│  localStorage   Org Chart    Pipeline             │
+│  (persist)      (render)     (execute)            │
+└──────────────────────────────────────────────────┘
+```