tikankika · tikankika · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -23,6 +23,9 @@ Thumbs.db
 
 # Claude Code dev-support — local only, never published (B7 exclusion: .claude/ stays out of the public artifact)
 .claude/
+# Root agent-instruction file — dev-tooling, untracked per ACDM ADR-017; the public
+# architecture reference lives in docs/ARCHITECTURE.md
+/CLAUDE.md
 
 # Local MCP server config (contains absolute paths)
 .mcp.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to Teaching Suite are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Changed
+
+- **The architecture and tool reference moved from `CLAUDE.md` to `docs/ARCHITECTURE.md`.** Per ACDM ADR-017's dev-tooling boundary, agent-instruction files are local tooling and stay out of the public artefact — teaching-suite was the last public repo in the family still shipping its root `CLAUDE.md`. The content now lives in a human-facing `docs/ARCHITECTURE.md` (same reference, conventional home); `CLAUDE.md` is untracked and gitignored, and all links (README's developer door, TEACHER_GUIDE, EXAMPLES_POLICY, examples, methodology) point at the new location.
+
 ## [0.6.0] - 2026-07-07
 
 ### Added

diff --git a/EXAMPLES_POLICY.md b/EXAMPLES_POLICY.md
@@ -16,7 +16,7 @@ documented answer: **no**.
 This applies to all illustrative and sample content, including:
 
 - `examples/` — worked walkthroughs and the artefacts they produce
-- Code and tool examples in `README.md`, `CLAUDE.md`, and `docs/`
+- Code and tool examples in `README.md` and `docs/`
 - Illustrative snippets inside the methodology documents (`methodology/`)
 - Test fixtures and sample inputs under `tests/`
 

diff --git a/README.md b/README.md
@@ -129,7 +129,7 @@ The interesting part is the **methodology**, not the plumbing — three nested c
 Clone, build, and point it at a folder. It is an MCP server (Node.js) that runs inside Claude Desktop.
 
 - [Quick start](#quick-start) — install, build, test, and the Claude Desktop configuration
-- [CLAUDE.md](CLAUDE.md) — architecture and the full tool reference
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture and the full tool reference
 
 ## Features
 
@@ -270,7 +270,7 @@ The real privacy guarantees are the `--workspace` lockdown and the absence of ne
 ## Documentation
 
 - [docs/TEACHER_GUIDE.md](docs/TEACHER_GUIDE.md) - How to work with Teaching Suite as a teacher
-- [CLAUDE.md](CLAUDE.md) - Architecture and tool reference
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Architecture and tool reference
 - [ROADMAP.md](ROADMAP.md) - Direction towards 1.0
 - [CHANGELOG.md](CHANGELOG.md) - Release history
 - [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute

diff --git a/CLAUDE.md → docs/ARCHITECTURE.md b/CLAUDE.md → docs/ARCHITECTURE.md
@@ -1,30 +1,28 @@
-# CLAUDE.md - Teaching Suite
-
-## Project Overview
+# Architecture
 
 Teaching Suite is an MCP (Model Context Protocol) server that scaffolds guided processes for teachers. It helps capture ideas, reflect on lessons, plan teaching, and track pedagogical goals.
 
 **Philosophy:** Process scaffolding, not automation. The teacher thinks, MCP structures.
 
 **Version:** 0.6.0
 
-## Architecture
+## Repository layout
 
 ```
 teaching-suite/
 ├── src/
 │   ├── index.ts                    # MCP server entry point
 │   │
 │   ├── tools/
-│   │   ├── core/                   # Core Tools (4 tools)
+│   │   ├── core/                   # Core tools (4 tools)
 │   │   │   ├── index.ts
 │   │   │   ├── workspace.ts        # Path validation, security
 │   │   │   ├── file-read.ts
 │   │   │   ├── file-write.ts
 │   │   │   ├── file-edit.ts
 │   │   │   └── file-search.ts
 │   │   │
-│   │   ├── composite/              # Composite Tools (6 tools)
+│   │   ├── composite/              # Composite tools (6 tools)
 │   │   │   ├── index.ts
 │   │   │   ├── capture-idea.ts           # Quick idea capture
 │   │   │   ├── intelligent-save.ts       # Smart file saving
@@ -33,7 +31,7 @@ teaching-suite/
 │   │   │   ├── quick-save-session.ts
 │   │   │   └── log-process-event.ts      # Append event to course process log
 │   │   │
-│   │   ├── mechanical/             # Mechanical Tools (7 tools)
+│   │   ├── mechanical/             # Mechanical tools (7 tools)
 │   │   │   ├── load-methodology.ts       # Load methodology docs
 │   │   │   ├── find-context.ts           # Search workspace for files (types derived from registry; Material/ recursive)
 │   │   │   ├── context-load.ts           # Load _config/ at session start
@@ -42,11 +40,11 @@ teaching-suite/
 │   │   │   ├── parse-lesson-plan-yaml.ts # Parse lesson-plan YAML
 │   │   │   └── aggregate-logs.ts         # Cross-server chronological timeline
 │   │   │
-│   │   ├── setup/                  # Setup Tools (2 tools)
+│   │   ├── setup/                  # Setup tools (2 tools)
 │   │   │   ├── project-init.ts           # Initialise course structure
 │   │   │   └── init-profession.ts        # Initialise Profession/Manifest/
 │   │   │
-│   │   └── sources/                # Source Tools (5 tools)
+│   │   └── sources/                # Source tools (5 tools)
 │   │       ├── index.ts
 │   │       ├── scan.ts
 │   │       └── track.ts
@@ -61,7 +59,7 @@ teaching-suite/
 │
 ├── methodology/                    # Pedagogical guides (for Claude Desktop)
 │   ├── README.md                   # Top-level operative guide (v3)
-│   ├── pedagogisk_arkitektur.md  # Conceptual spine (v3)
+│   ├── pedagogisk_arkitektur.md    # Conceptual spine (v3)
 │   ├── synlighetsprincip.md        # Visibility principle (v3)
 │   ├── tensions.md                 # Pedagogical tensions (v3)
 │   ├── lesson/                     # Lesson cycle (v3): pre_lesson, post_lesson_auto, post_lesson_refl, bridge
@@ -79,13 +77,12 @@ teaching-suite/
 │
 ├── tests/                          # Test suite (Vitest)
 │
-├── CLAUDE.md                       # This file
 └── package.json
 ```
 
-## Tool Inventory (24 tools)
+## Tool inventory (24 tools)
 
-### Core Tools (4)
+### Core tools (4)
 
 | Tool | Purpose |
 |------|---------|
@@ -94,9 +91,9 @@ teaching-suite/
 | `file_edit` | Edit existing files (replace, insert, append, delete) |
 | `file_search` | Search text across files in workspace |
 
-All core tools enforce **workspace validation** via `--workspace` flag.
+All core tools enforce **workspace validation** via the `--workspace` flag.
 
-### Composite Tools (6)
+### Composite tools (6)
 
 | Tool | Purpose |
 |------|---------|
@@ -107,7 +104,7 @@ All core tools enforce **workspace validation** via `--workspace` flag.
 | `quick_save_session` | Full workflow: capture → format → save |
 | `log_process_event` | Append a structured event to the course process log |
 
-### Mechanical Tools (7)
+### Mechanical tools (7)
 
 | Tool | Purpose |
 |------|---------|
@@ -119,14 +116,14 @@ All core tools enforce **workspace validation** via `--workspace` flag.
 | `parse_lesson_plan_yaml` | Parse a lesson plan's YAML frontmatter and body |
 | `aggregate_logs` | Unified chronological timeline across Teaching Suite, QuestionForge, Assessment Suite |
 
-### Setup Tools (2)
+### Setup tools (2)
 
 | Tool | Purpose |
 |------|---------|
 | `project_init` | Create folder structure, copy methodology docs, initialise project state |
 | `init_profession` | Initialise workspace-level `Profession/Manifest/` (sibling to course folders) |
 
-### Source Tools (5)
+### Source tools (5)
 
 | Tool | Purpose |
 |------|---------|
@@ -136,7 +133,7 @@ All core tools enforce **workspace validation** via `--workspace` flag.
 | `source_remove` | Remove source by role |
 | `source_update_usage` | Track source usage |
 
-## Course Workspace Structure
+## Course workspace structure
 
 When `project_init` is called with `type: 'course'`, it creates this structure in the workspace:
 
@@ -165,12 +162,12 @@ When `project_init` is called with `type: 'course'`, it creates this structure i
 │  — Course material —
 ├── Styrdokument/                   # Syllabus, curriculum, commentary
 ├── Material/                       # Course material (own + imported)
-│   ├── WIP/                       # Work in progress (drafts)
-│   ├── Klart/                     # Ready for lesson
-│   │   ├── Presentationer/        # .pptx, .pdf
-│   │   ├── Övningar/              # Exercises, lab instructions
-│   │   └── Övrigt/                # Films, links, handouts
-│   └── Resurser/                  # Imported (others' material, references)
+│   ├── WIP/                        # Work in progress (drafts)
+│   ├── Klart/                      # Ready for lesson
+│   │   ├── Presentationer/         # .pptx, .pdf
+│   │   ├── Övningar/               # Exercises, lab instructions
+│   │   └── Övrigt/                 # Films, links, handouts
+│   └── Resurser/                   # Imported (others' material, references)
 ├── Exams/                          # Exams, QuestionForge material
 │
 │  — System —
@@ -182,7 +179,7 @@ When `project_init` is called with `type: 'course'`, it creates this structure i
 
 For non-course types (e.g., `lesson`), the legacy flat structure is used: `Reflections/`, `Lesson_Plans/`, `Ideas/`, etc.
 
-## MCP Ecosystem
+## MCP ecosystem
 
 Teaching Suite is one of several MCP servers that share the same Nextcloud workspace:
 
@@ -208,7 +205,7 @@ QuestionForge (qf-scaffolding-v2, qf-pipeline-v2)
 
 **Separation principle:** Teaching Suite handles the teacher's professional processes. Assessment data (student work, grades) stays in Assessment Suite's own workspace. Only *insights about teaching* flow back.
 
-## Workspace Security
+## Workspace security
 
 All file operations require a `--workspace` flag at server startup:
 
@@ -227,7 +224,7 @@ All file operations require a `--workspace` flag at server startup:
 - Path traversal attempts (e.g., `../../etc/passwd`) are blocked
 - The content scanner (`content-scanner.ts`) is an **advisory** keyword matcher: it flags a small set of Swedish privacy/exam-related terms in content and surfaces a warning. It does **not** detect names or personal numbers, does not anonymise, and never blocks an operation. It is a reminder, not a guarantee — anonymise sensitive data before importing it.
 
-## Key Commands
+## Key commands
 
 ```bash
 npm install    # Install dependencies
@@ -236,15 +233,15 @@ npm test       # Run the full test suite
 npm start      # Start MCP server
 ```
 
-## Design Principles
+## Design principles
 
 1. **Methodology = Pedagogik** (markdown files for Claude Desktop)
-2. **Core Tools = Teknik** (generic MCP tools)
+2. **Core tools = Teknik** (generic MCP tools)
 3. **Claude Desktop = Orkestrering** (reads methodology, uses tools)
 4. **Teacher THINKS, MCP STRUCTURES**
 5. **Never start from scratch** (build on history)
 
-## Language Policy
+## Language policy
 
 This project is **deliberately bilingual**. Swedish teachers are the primary
 audience, so teacher-facing content stays in Swedish; the code stays in English
@@ -256,9 +253,9 @@ for international contributors. This is a design choice, not a translation backl
 - **English-language content** (README, CONTRIBUTING, international-facing docs): British English — see ADR-007 (`docs/decisions/ADR-007-bilingual-language-policy.md`)
 - **Why**: English code lowers the barrier for international contributors; Swedish UX and methodology because the teachers who use this tool think and work in Swedish. Translating the methodology to English would not serve the primary audience.
 
-## Session Workflow
+## Session workflow
 
-When to use session capture tools:
+When to use the session capture tools:
 
 1. **During conversation** — ideas emerge naturally
 2. **At session end** — `quick_save_session` to persist everything

diff --git a/docs/TEACHER_GUIDE.md b/docs/TEACHER_GUIDE.md
@@ -251,4 +251,4 @@ not to automate the thinking away.
 ---
 
 *For the methodology, see the cycle folders in `methodology/` (`lesson/`, `course/`,
-`profession/`); for architecture and the full tool reference, see `CLAUDE.md`.*
+`profession/`); for architecture and the full tool reference, see `docs/ARCHITECTURE.md`.*
diff --git a/docs/decisions/ADR-009-claude-md-exclusion.md b/docs/decisions/ADR-009-claude-md-exclusion.md
@@ -0,0 +1,63 @@
+---
+type: decision
+status: active
+created: 2026-07-07
+origin: code
+project: teaching-suite
+relates_to: [ADR-007]
+---
+
+# ADR-009: Root `CLAUDE.md` is dev-tooling — the public reference lives in `docs/ARCHITECTURE.md`
+
+## Context
+
+ACDM ADR-017 (2026-06-24) settled that `.claude/` is local dev-tooling and is
+gitignored in every downstream repo; the public form of any policy lives in
+conventional docs. It left one artefact undecided for this repo: the root
+`CLAUDE.md`, which teaching-suite alone in the family still shipped publicly
+(QuestionForge and Assessment Suite never tracked theirs; edusafe-pipeline
+excludes it at its public flip). The file doubled as the project's architecture
+and tool reference, and README's developer door linked to it.
+
+## Problem
+
+Should teaching-suite keep shipping its root `CLAUDE.md` publicly, or align
+with the family boundary — and if it aligns, where does the architecture
+reference go?
+
+## Alternatives considered
+
+1. **Keep `CLAUDE.md` public.** It contained nothing sensitive and served as
+   the developer reference. Rejected: it is an agent-instruction file by name
+   and convention, and keeping it tracked leaves the family inconsistent —
+   the same rationale ADR-017 rejected for `.claude/rules/`.
+2. **Keep it public and document the exception.** Rejected: the exception has
+   no benefit over a conventional docs file; readers expect architecture in
+   `docs/`, not in an agent file.
+3. **Exclude it; move the reference to `docs/ARCHITECTURE.md`. (chosen)**
+   The content is architecture documentation and gets a human-facing home;
+   the agent file becomes local dev-tooling like everything else under
+   `.claude/`.
+
+## Decision
+
+- The architecture and full tool reference lives in **`docs/ARCHITECTURE.md`**
+  (tracked, public, human-facing).
+- Root **`CLAUDE.md` is untracked and gitignored** (`/CLAUDE.md`,
+  root-anchored). It remains on disk as a thin local pointer that imports
+  `docs/ARCHITECTURE.md`, so agent sessions and public readers share one
+  source of truth — the architecture is edited in `docs/ARCHITECTURE.md`,
+  never in the pointer.
+
+## Consequences
+
+- No public repo in the family ships agent-instruction files; the B7
+  exclusion (`.claude/` out of the public artefact) extends to root
+  `CLAUDE.md`.
+- All public links (README developer door, TEACHER_GUIDE, EXAMPLES_POLICY,
+  examples, methodology) point at `docs/ARCHITECTURE.md`.
+- The historical `CLAUDE.md` revisions remain in git history; nothing
+  sensitive was in them (reviewed — architecture reference only).
+- A fresh clone has no root `CLAUDE.md`; contributors read
+  `docs/ARCHITECTURE.md`, and ACDM's `init_project` can seed a local pointer
+  where needed.
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
@@ -12,6 +12,7 @@ point-in-time records of significant design decisions and why they were made.
 | [ADR-005](ADR-005-parse-lesson-transcript-mode-parameter.md) | `parse_lesson_transcript` mode parameter |
 | [ADR-007](ADR-007-bilingual-language-policy.md) | Bilingual language policy |
 | [ADR-008](ADR-008-license-polyform-noncommercial.md) | Licence — PolyForm Noncommercial |
+| [ADR-009](ADR-009-claude-md-exclusion.md) | Root `CLAUDE.md` is dev-tooling — public reference in `docs/ARCHITECTURE.md` |
 
 (ADR-006 was never issued; the numbering gap is intentional.)
 

diff --git a/examples/README.md b/examples/README.md
@@ -27,5 +27,5 @@ Start with the walkthrough README.
 
 > **Note on language.** The reflection content is in Swedish — Teaching Suite's
 > primary audience is Swedish teachers, and teacher-facing artifacts stay in
-> Swedish (see the Language Policy in the root `CLAUDE.md`). The walkthrough
+> Swedish (see the Language policy in `docs/ARCHITECTURE.md`). The walkthrough
 > prose is in English.
diff --git a/methodology/shared_principles.md b/methodology/shared_principles.md
@@ -301,7 +301,7 @@ Extraktion (auto-pipeline) och tolkning (Gibbs) är kategoriskt olika kognitiva
 - Auto-pipeline = "vad hände" (data, timing, begrepp, uppgifter — mekaniskt)
 - Gibbs = "vad betyder det" (meningsskapande, känslor, pedagogiska beslut — manuellt)
 
-Att bunta ihop dem skulle tvinga läraren genom hela pipelinen varje gång, och skulle blurra att de är olika saker. Separeringen respekterar `Teacher THINKS, MCP STRUCTURES`-principen från CLAUDE.md.
+Att bunta ihop dem skulle tvinga läraren genom hela pipelinen varje gång, och skulle blurra att de är olika saker. Separeringen respekterar `Teacher THINKS, MCP STRUCTURES`-principen från `docs/ARCHITECTURE.md`.
 
 ---