fleet-standard: .terraphim knowledge stack (roles, KG, thesauri, skills manifest, memory)

.terraphim/README.md

@@ -89,3 +89,30 @@ When adding new concepts:
 2. Include synonyms using the `synonyms::` directive
 3. Regenerate the thesaurus JSON
 4. Test with `terraphim-grep --role {role} --answer "your query"`
+
+
+## Fleet roles (added 2026-08-08)
+
+Additional Terraphim-AI domain roles (fleet standard §8):
+
+| Role | shortname | KG |
+|------|-----------|-----|
+| Terraphim AI Developer | `taidev` | `.terraphim/kg-taidev/` |
+| Terraphim AI Architect | `taiarch` | `.terraphim/kg-taiarch/` |
+
+These coexist with the existing `Rust Engineer` / `kg/<role>/` layout.
+
+```bash
+python3 .terraphim/scripts/bootstrap.py   # materialize {REPO} + refresh thesauri
+```
+
+Skills manifest: `.terraphim/skills.toml` (`tsm install <name>`).
+Repo agent memory: `memory/` at repo root.
+
+## Path portability
+
+Fleet roles use **repo-relative** haystack and KG paths (`.`, `crates`, `memory`, …).
+`scripts/bootstrap.py` regenerates thesauri and normalizes absolute/`{REPO}` paths
+that resolve **inside this repo** back to relative form. Foreign absolute haystacks
+are left untouched. The script never writes machine-absolute paths into tracked config.
+

.terraphim/config.json

@@ -31,6 +31,112 @@
       "llm_provider": "ollama",
       "ollama_model": "llama3.2:3b",
       "ollama_base_url": "http://127.0.0.1:11434"
+    },
+    "Terraphim AI Developer": {
+      "shortname": "taidev",
+      "name": "Terraphim AI Developer",
+      "relevance_function": "terraphim-graph",
+      "terraphim_it": true,
+      "theme": "united",
+      "kg": {
+        "automata_path": null,
+        "knowledge_graph_local": {
+          "input_type": "markdown",
+          "path": ".terraphim/kg-taidev"
+        },
+        "public": false,
+        "publish": false
+      },
+      "haystacks": [
+        {
+          "location": ".",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        },
+        {
+          "location": "crates",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        },
+        {
+          "location": "memory",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        }
+      ],
+      "llm_enabled": false,
+      "llm_provider": "ollama",
+      "ollama_model": "llama3.2:3b",
+      "ollama_base_url": "http://127.0.0.1:11434",
+      "llm_router_enabled": false,
+      "llm_context_window": 32768,
+      "extra": {}
+    },
+    "Terraphim AI Architect": {
+      "shortname": "taiarch",
+      "name": "Terraphim AI Architect",
+      "relevance_function": "terraphim-graph",
+      "terraphim_it": true,
+      "theme": "united",
+      "kg": {
+        "automata_path": null,
+        "knowledge_graph_local": {
+          "input_type": "markdown",
+          "path": ".terraphim/kg-taiarch"
+        },
+        "public": false,
+        "publish": false
+      },
+      "haystacks": [
+        {
+          "location": ".",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        },
+        {
+          "location": "docs",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        },
+        {
+          "location": ".docs",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        },
+        {
+          "location": "memory",
+          "service": "Ripgrep",
+          "read_only": true,
+          "fetch_content": false,
+          "atomic_server_secret": null,
+          "extra_parameters": {}
+        }
+      ],
+      "llm_enabled": false,
+      "llm_provider": "ollama",
+      "ollama_model": "llama3.2:3b",
+      "ollama_base_url": "http://127.0.0.1:11434",
+      "llm_router_enabled": false,
+      "llm_context_window": 32768,
+      "extra": {}
     }
   }
 }

.terraphim/kg-taiarch/knowledge-graph.md

@@ -0,0 +1,5 @@
+# Knowledge Graph
+
+Local-first KG: logseq-style markdown concepts with `synonyms::` lines compile to per-role thesauri; drives term expansion, automata, and graph ranking.
+
+synonyms:: knowledge graph, kg, thesaurus, synonyms, logseq, concept, term expansion

.terraphim/kg-taiarch/privacy.md

@@ -0,0 +1,5 @@
+# Local-First Privacy
+
+No telemetry, local persistence, optional remote haystacks are explicit per role. Secrets via op:// references, never committed.
+
+synonyms:: privacy, local-first, no telemetry, offline

.terraphim/kg-taiarch/relevance.md

@@ -0,0 +1,5 @@
+# Relevance Functions
+
+Pluggable ranking: title-scorer, terraphim-graph (rolegraph), BM25 variants. Selected per role in config.
+
+synonyms:: relevance, ranking, title-scorer, bm25, scorer, rank

.terraphim/kg-taiarch/role.md

@@ -0,0 +1,5 @@
+# Roles
+
+A role bundles a KG, haystacks, relevance function, and theme. Users/agents switch roles to change knowledge domain. Roles defined in config JSON.
+
+synonyms:: role, roles, role config, default_role, selected_role, haystack set

.terraphim/kg-taiarch/search-pipeline.md

@@ -0,0 +1,5 @@
+# Search Pipeline
+
+Query → thesaurus expansion (automata) → haystack fetch → merge → relevance rank → results. Async via tokio; middleware crate provides the axum service.
+
+synonyms:: pipeline, search flow, query expansion, middleware, axum, async search

.terraphim/kg-taidev/agent.md

@@ -0,0 +1,5 @@
+# Terraphim Agent
+
+Agent crates (`terraphim_agent` + `terraphim-agent` binary): REPL with /search /role /graph, hooks handler, guard, learning capture, robot mode JSON for AI integration.
+
+synonyms:: agent, repl, terraphim-agent, hook, guard, robot mode, learning capture, /search, /role, /graph

.terraphim/kg-taidev/automata.md

@@ -0,0 +1,5 @@
+# Automata
+
+Core text automaton crate (`terraphim_automata`): Aho-Corasick based matching over the role thesaurus, autocomplete, and term linking. Foundation of KG-driven search and hooks text replacement.
+
+synonyms:: automata, aho-corasick, automaton, thesaurus, autocomplete, matcher, linkify, term linking, AutomataPath, TerraphimAutomata

.terraphim/kg-taidev/config.md

@@ -0,0 +1,5 @@
+# Config & Secrets
+
+`terraphim_config` + `terraphim_onepassword_cli` (in terraphim-config-persistence): role config loading, SecretLoader resolving op://vault/item/field via 1Password CLI with EnvironmentLoader fallback.
+
+synonyms:: config, settings, secret, 1password, op://, SecretLoader, EnvironmentLoader, vault

.terraphim/kg-taidev/haystack.md

@@ -0,0 +1,5 @@
+# Haystacks
+
+Search source crates (`haystack_*`): Ripgrep local files, GrepApp GitHub code search, QueryRs Rust docs, Atomic server, JMAP mail, Atlassian, Discourse. Each role configures its own haystacks.
+
+synonyms:: haystack, ripgrep, grepapp, queryrs, atomic, jmap, atlassian, discourse, data source, search source

.terraphim/kg-taidev/hooks.md

@@ -0,0 +1,5 @@
+# Hooks
+
+`terraphim_hooks`: KG-driven text replacement and validation hooks (pre-commit, Claude Code integration).
+
+synonyms:: hooks, text replacement, validate, pre-commit, replace

.terraphim/kg-taidev/mcp.md

@@ -0,0 +1,5 @@
+# MCP Server
+
+`terraphim_mcp_server`: exposes Terraphim search as MCP tools for Claude Code / agents.
+
+synonyms:: mcp, mcp server, model context protocol, mcp tools, search tool

.terraphim/kg-taidev/orchestrator.md

@@ -0,0 +1,5 @@
+# Multi-Agent Orchestration
+
+Agent fleet crates (`terraphim_orchestrator`, `terraphim_multi_agent`, `terraphim_agent_supervisor`, `terraphim_agent_registry`, `terraphim_agent_messaging`, `terraphim_agent_evolution`): spawn, supervise, message and evolve agent fleets.
+
+synonyms:: orchestrator, multi-agent, supervisor, registry, messaging, evolution, spawner, fleet, swarm

.terraphim/kg-taidev/persistence.md

@@ -0,0 +1,5 @@
+# Persistence
+
+Storage layer (`terraphim_persistence`): DeviceStorage over OpenDAL with memory/dashmap/redb/sqlite/s3 profiles, multi-profile cache write-back, settings persistence.
+
+synonyms:: persistence, storage, opendal, redb, sqlite, dashmap, DeviceStorage, settings, cache, write-back, memory backend, s3 backend

.terraphim/kg-taidev/rolegraph.md

@@ -0,0 +1,5 @@
+# Rolegraph
+
+Graph ranking crate (`terraphim_rolegraph`): builds the co-occurrence graph over documents for a role and ranks results (terraphim-graph relevance function).
+
+synonyms:: rolegraph, role graph, co-occurrence, graph rank, terraphim-graph, relevance, RoleGraph, graph ranking

.terraphim/kg-taidev/session.md

@@ -0,0 +1,5 @@
+# Sessions
+
+`terraphim_sessions` + `terraphim-session-analyzer`: agent session capture, analysis, resume.
+
+synonyms:: session, sessions, session analyzer, resume, transcript

.terraphim/scripts/bootstrap.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Bootstrap .terraphim for this clone.
+
+- Regenerates thesaurus-<shortname>.json from kg-<shortname>/*.md when that
+  fleet-style directory exists
+- Normalizes accidental absolute/{REPO} haystack paths back to repo-relative
+- Does NOT rewrite legacy kg/<role>/ paths (e.g. .terraphim/kg/rust-engineer)
+- NEVER writes machine-absolute paths into tracked config.json
+
+Idempotent. Run after clone and after editing concept files.
+"""
+from __future__ import annotations
+
+import glob
+import json
+import os
+import subprocess
+
+REPO = subprocess.check_output(
+    ["git", "rev-parse", "--show-toplevel"], text=True
+).strip()
+TD = os.path.join(REPO, ".terraphim")
+CFG = os.path.join(TD, "config.json")
+
+
+def compile_thesaurus(kg_dir: str, out_path: str, role_name: str) -> None:
+    if not os.path.isdir(kg_dir):
+        print(f"  skip thesaurus (missing {os.path.relpath(kg_dir, REPO)})")
+        return
+    data: dict = {}
+    cid = 100
+    for f in sorted(glob.glob(os.path.join(kg_dir, "*.md"))):
+        nterm = os.path.splitext(os.path.basename(f))[0]
+        txt = open(f, encoding="utf-8").read()
+        syn = next(
+            (
+                l.split("::", 1)[1]
+                for l in txt.splitlines()
+                if l.strip().lower().startswith("synonyms::")
+            ),
+            "",
+        )
+        for term in dict.fromkeys(
+            [nterm] + [s.strip().lower() for s in syn.split(",") if s.strip()]
+        ):
+            key = term.lower()
+            if key in data and data[key]["nterm"] != nterm:
+                print(
+                    f"  warn: synonym {key!r} already maps to {data[key]['nterm']!r}; "
+                    f"ignoring mapping to {nterm!r} ({os.path.basename(f)})"
+                )
+                continue
+            data.setdefault(key, {"id": cid, "nterm": nterm})
+        cid += 1
+    with open(out_path, "w", encoding="utf-8") as fh:
+        json.dump({"name": role_name, "data": data}, fh, indent=2)
+        fh.write("\n")
+    print(f"  wrote {os.path.relpath(out_path, REPO)} ({len(data)} terms)")
+
+
+def to_repo_relative(loc: str) -> str:
+    if loc in ("{REPO}", ".", ""):
+        return "."
+    if loc.startswith("{REPO}/"):
+        return loc[len("{REPO}/") :] or "."
+    if loc == REPO or loc.rstrip("/") == REPO:
+        return "."
+    if loc.startswith(REPO + os.sep):
+        return loc[len(REPO) + 1 :] or "."
+    if loc.startswith("/"):
+        # Only rewrite absolute paths that resolve INSIDE this repo.
+        # Never rewrite foreign paths that merely share a directory suffix
+        # (e.g. /mnt/shared/docs must not become "docs").
+        try:
+            real_loc = os.path.realpath(loc)
+            real_repo = os.path.realpath(REPO)
+        except OSError:
+            return loc
+        if real_loc == real_repo:
+            return "."
+        prefix = real_repo + os.sep
+        if real_loc.startswith(prefix):
+            return real_loc[len(prefix):] or "."
+        # foreign absolute path — leave untouched
+        return loc
+    return loc
+
+
+cfg = json.load(open(CFG))
+changed = False
+for role in cfg.get("roles", {}).values():
+    short = role.get("shortname") or role.get("name", "role").lower().replace(" ", "-")
+    fleet_kg = os.path.join(TD, f"kg-{short}")
+    kg = role.get("kg", {}).get("knowledge_graph_local")
+    # Only force fleet path when fleet kg-<short> dir exists; leave legacy kg/<name>
+    if kg and "path" in kg and os.path.isdir(fleet_kg):
+        rel = f".terraphim/kg-{short}"
+        if kg["path"] != rel:
+            kg["path"] = rel
+            changed = True
+    elif kg and "path" in kg:
+        # legacy kg/<role>/ — heal via same relative normalizer (no layout change)
+        new_p = to_repo_relative(kg["path"])
+        if new_p == ".":
+            new_p = kg["path"]  # don't collapse a kg path to repo root
+        if kg["path"] != new_p:
+            kg["path"] = new_p
+            changed = True
+    for h in role.get("haystacks", []):
+        new = to_repo_relative(h.get("location", "."))
+        if h.get("location") != new:
+            h["location"] = new
+            changed = True
+    if os.path.isdir(fleet_kg):
+        compile_thesaurus(
+            fleet_kg,
+            os.path.join(TD, f"thesaurus-{short}.json"),
+            role.get("name", short),
+        )
+
+if changed:
+    with open(CFG, "w", encoding="utf-8") as fh:
+        json.dump(cfg, fh, indent=2)
+        fh.write("\n")
+    print("  config.json normalized (portable relative paths)")
+else:
+    print("  config.json already portable (no path rewrite)")
+print("done.")

.terraphim/skills.toml

@@ -0,0 +1,28 @@
+# Terraphim skills manifest for agents working in this repository.
+# Install with: tsm install <name>  (all marketplace skills currently premium — `tsm login` required)
+# Registry: https://terraphim-skills.md
+# Names verified against `tsm list` 2026-08-08.
+
+[required]
+skills = [
+  "disciplined-research",
+  "disciplined-specification",
+  "disciplined-design",
+  "disciplined-implementation",
+  "disciplined-verification",
+  "disciplined-validation",
+  "code-review",
+  "debugging",
+  "handover",
+  "learning-capture",
+  "git-safety-guard",
+]
+
+[recommended]
+skills = [
+  "architecture",
+  "documentation",
+  "kg-rlm-ingest",
+  "gitea-pagerank-workflow",
+  "deterministic-rlm-review",
+]