refactor: restore Makefile, document two usage modes

The framework supports both technical operations (SSH/screen/CLI/harness)
and knowledge work (Hermes/OWUI/Conduit via MCP/API). The Makefile is
restored as a convenience layer over the scripts — use make or call
scripts directly, whichever fits the interface you're working through.

README rewritten with a Mode 1 / Mode 2 comparison table. AGENTS.md key
commands now show both make and direct script invocation. ADOPTING.md
updated to use make shorthand.

The scripts remain the real entry points; make is shorthand. Mode 2
agents invoke the same scripts via container exec or MCP tool calls.

💘 Generated with Crush

Assisted-by: Crush via Crush <crush@charm.land>

ADOPTING.md

@@ -16,8 +16,8 @@ tea repo create --owner <org> --name <project> --template-from TSYSGroupCorporat
 # or clone directly:
 git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git <project>
 cd <project>
-bash scripts/setup-hooks.sh    # install git hooks
+make setup     # install git hooks (= bash scripts/setup-hooks.sh)
-bash scripts/check-rules.sh --fast   # verify baseline
+make fast      # verify baseline (= bash scripts/check-rules.sh --fast)
 ```
 
 Then edit `AGENTS.md` (fill bracketed fields), override `scripts/test.sh`, and start work.

AGENTS.md

@@ -50,6 +50,7 @@ Replace this bracketed text.>
 │   ├── up.sh / down.sh  ← docker compose lifecycle wrappers
 │   ├── garden.sh        ← doc-sprawl / Discourse-migration report
 │   └── lib/common.sh    ← shared bash library (colors, log_*, docker_run, check)
+├── Makefile             ← convenience dispatch (setup/validate/fast/lint/test/garden/up/down/status)
 ├── docker-compose.yml.example  ← lifecycle template (copy to docker-compose.yml)
 ├── .env.example         ← copy to .env, fill in secrets
 └── .crush/memory/       ← operational memory read each session (if using Crush)
@@ -145,16 +146,21 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
 
 ## Key Commands
 
+At a terminal (Mode 1), use `make` or call scripts directly:
+
 ```bash
-bash scripts/setup-hooks.sh    # install git hooks (run once after clone)
+bash scripts/setup-hooks.sh          # make setup   — install git hooks
-bash scripts/check-rules.sh --fast   # fast rule audit (pre-commit equivalent)
+bash scripts/check-rules.sh --fast   # make fast    — fast audit (pre-commit)
-bash scripts/check-rules.sh          # full audit (includes test suite)
+bash scripts/check-rules.sh          # make validate — full audit (incl tests)
-bash scripts/test.sh                 # run the test suite (override per project)
+bash scripts/test.sh                 # make test    — run test suite
-bash scripts/garden.sh               # doc-sprawl / Discourse-migration report
+bash scripts/garden.sh               # make garden  — doc-sprawl report
-bash scripts/up.sh                   # bring up the docker-compose stack
+bash scripts/up.sh                   # make up      — bring up stack
-bash scripts/down.sh                 # bring it down
+bash scripts/down.sh                 # make down    — bring down stack
 ```
 
+Via MCP/API (Mode 2): invoke the same scripts through container exec or MCP
+tool calls. The scripts are the real entry points; `make` is shorthand.
+
 ## Enforcement Model (belt and suspenders)
 
 Policy is enforced by **git hooks** (portable, harness-agnostic): `scripts/pre-commit`

Makefile

@@ -0,0 +1,46 @@
+# Makefile — convenience dispatch to scripts/.
+#
+# Not required. The scripts in scripts/ are the real entry points and work
+# standalone. This file just gives you short verbs if you're at a terminal.
+#
+# In Mode 2 (Hermes/OWUI/MCP), agents call the scripts directly or via API —
+# they don't need this file.
+
+.PHONY: setup validate fast lint test garden up down status clean help
+
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+setup: ## Install git hooks
+	@bash scripts/setup-hooks.sh
+
+validate: ## Full rule audit (includes tests)
+	@bash scripts/check-rules.sh
+
+fast: ## Fast rule audit (pre-commit equivalent)
+	@bash scripts/check-rules.sh --fast
+
+lint: ## Lint shell scripts (shellcheck via docker)
+	@docker run --rm -v "$$(pwd):/mnt" koalaman/shellcheck:stable \
+		$$(find . -path ./.git -prune -o -path ./.tmp -prune -o -path ./vendor -prune -o -path ./node_modules -prune -o \( -name '*.sh' -o -name '*.bash' \) -print | sed 's|^\./|/mnt/|') || true
+
+test: ## Run the test suite (override per project)
+	@bash scripts/test.sh
+
+garden: ## Doc-sprawl / Discourse-migration report
+	@bash scripts/garden.sh
+
+up: ## Bring up the docker-compose stack
+	@bash scripts/up.sh
+
+down: ## Bring down the docker-compose stack
+	@bash scripts/down.sh
+
+status: ## Show repo status snapshot
+	@echo "== branch =="; git branch --show-current 2>/dev/null || echo "(no branch)"
+	@echo "== last commit =="; git log --oneline -1 2>/dev/null || true
+	@echo "== working tree =="; git status --short 2>/dev/null || echo "(not a git repo)"
+	@echo "== STATUS.md head =="; sed -n '1,12p' STATUS.md 2>/dev/null || echo "(no STATUS.md)"
+
+clean: ## Remove build/test artifacts (override per project)
+	@echo "make clean: nothing to clean — override this in your project's Makefile."

README.md

@@ -1,33 +1,40 @@
 # TSYSGroupAIOS — cross-project best-practices framework
 
-This repo serves a single purpose: **capture the operating knowledge that makes
+This repo captures the operating knowledge that makes AI agents effective and
-AI agents effective, and make it portable to any agent interface.**
+makes it work across **two usage modes**:
 
-It works in three layers — use whichever you need:
+| | Mode 1: Technical Operations | Mode 2: Knowledge Work |
+|---|---|---|
+| **Interface** | SSH, screen, CLI | Web/app UI (Hermes, OWUI, Conduit) |
+| **Agent** | Harness in a terminal (Crush, etc.) | Hermes/OWUI with docker/k8s/MCP |
+| **Systems access** | CLI tools (ssh, conman, redmine-cli, discourse-cli) | MCP servers, API calls, container exec |
+| **Focus** | Infra ops, switches, VMs, IAC | Document production, knowledge synthesis |
+| **Who** | Engineers and ops agents | Anyone (including non-CLI users) |
 
-## Layer 1: Knowledge (works everywhere)
+Both modes share the same knowledge base. The difference is how the agent
+touches systems: CLI tools vs MCP/APIs.
 
-The markdown files are the core product. Any agent — Crush, OpenWebUI, Hermes,
+## The knowledge base (both modes)
-Conduit on an iPhone — reads them. No CLI, no git, no SSH required.
 
-| File | What it does |
+These markdown files are the core. Any agent reads them — no CLI required.
+
+| File | Purpose |
 |---|---|
-| **[BASELINE-PROMPT.md](BASELINE-PROMPT.md)** | The global working principles (13 sections). Paste into any agent's system prompt. |
+| **[BASELINE-PROMPT.md](BASELINE-PROMPT.md)** | The 13-section global working principles. Load into any agent's system prompt. |
-| **AGENTS.md** | Project-level policy skeleton. Any agent that reads files picks this up automatically. |
+| **AGENTS.md** | Project-level policy. Agents that read files pick this up automatically. |
 | **[ADOPTING.md](ADOPTING.md)** | How to bring an existing project under this framework. |
 | **[PATTERNS.md](PATTERNS.md)** | Why every decision was made (pattern extraction from 18 projects). |
 | **STATUS.md** | Agent scratchpad template (token-efficiency, not system of record). |
 | **WORKING.md** | Task tracker template (the only in-repo task list). |
-| **questions-v1.md** | Git-tracked question log template for the human. |
+| **questions-v1.md** | Git-tracked question log for the human. |
 
-**For non-CLI users (e.g. Conduit/iPhone/Hermes):** load `BASELINE-PROMPT.md`
+**Mode 2 minimal setup:** load `BASELINE-PROMPT.md` into the agent's system
-into the agent's system prompt. That alone carries the operating principles.
+prompt. Add `AGENTS.md` as project context. That's it — the agent has the full
-Add `AGENTS.md` as project context for project-specific policy.
+operating discipline without touching a CLI.
 
-## Layer 2: Git hooks (for projects using git)
+## Mode 1: CLI tools (SSH/screen/harness)
 
-When a project uses git, copy in the enforcement scripts for mechanical checks
+For technical operations. Scripts provide enforcement and lifecycle:
-at commit/push time. Works under any agent — no harness coupling.
 
 ```
 scripts/
@@ -36,32 +43,40 @@ scripts/
 ├── pre-push          ← full audit + clean-tree gate
 ├── check-rules.sh    ← the rule audit engine
 ├── test.sh           ← project test runner (override per project)
+├── docker-run.sh     ← canonical ephemeral-container wrapper
+├── up.sh / down.sh   ← docker compose lifecycle wrappers
 ├── garden.sh         ← doc-sprawl / Discourse-migration report
 └── lib/common.sh     ← shared bash library
 ```
 
-## Layer 3: Docker lifecycle (for containerized projects)
+A `Makefile` provides short verbs (`make setup`, `make validate`, `make fast`,
+etc.) as a convenience. The scripts work standalone too — use whichever you prefer.
 
-```
+### What the enforcement layer checks
-scripts/docker-run.sh    ← canonical ephemeral-container wrapper
-scripts/up.sh            ← docker compose up
-scripts/down.sh          ← docker compose down
-docker-compose.yml.example  ← lifecycle template
-```
 
-## What it enforces (layer 2)
+`scripts/check-rules.sh` runs: shellcheck (zero info-level), Docker image
+pinning (no `:latest`), container naming, required files, doc freshness,
+Discourse pointer-headers, WORKING.md completion, CNW markers, hygiene,
+test suite.
 
-`scripts/check-rules.sh` runs these checks:
+## Mode 2: Hermes/OWUI/MCP (emerging)
-- **shellcheck** (zero warnings incl. info-level, via Docker)
+
-- **Docker image pinning** (no `:latest`)
+For knowledge work and non-CLI users. No SSH or screen required.
-- **Container naming** (explicit `container_name:`, never Docker defaults)
+
-- **Required files** (AGENTS.md, STATUS.md, questions-v1.md, .env.example, etc.)
+The same scripts can be invoked via MCP tool calls or container exec. To adapt:
-- **Doc freshness** (STATUS.md updated today)
+
-- **Discourse pointer-header** (non-exempt .md must cite a Discourse URL)
+1. Load `BASELINE-PROMPT.md` into the agent's system prompt.
-- **WORKING.md completion** (no unchecked tasks at commit time)
+2. Point the agent at `AGENTS.md` for project policy.
-- **CNW markers** (unresolved questions flagged)
+3. Replace CLI tools with MCP equivalents:
-- **Hygiene** (no merge-conflict markers)
+   - `redmine-cli` → Redmine MCP server
-- **Test suite** (scripts/test.sh, in full audit only)
+   - `discourse-cli` → Discourse MCP server
+   - `ssh/conman` → docker exec / k8s API / infrastructure MCP
+4. If the project uses git, the hook scripts run the same checks whether
+   triggered by a CLI commit or an MCP-initiated one.
+
+Over time, the framework will gain MCP-native enforcement paths. Today, the
+prose policy in `BASELINE-PROMPT.md` + `AGENTS.md` carries the discipline
+even with zero tooling.
 
 ## Creating a new project from this template
 
@@ -71,8 +86,8 @@ Or clone and go:
 ```bash
 git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git my-project
 cd my-project
-bash scripts/setup-hooks.sh
+make setup    # or: bash scripts/setup-hooks.sh
-bash scripts/check-rules.sh --fast
+make fast     # or: bash scripts/check-rules.sh --fast
 ```
 
 Fill in bracketed fields in `AGENTS.md`, override `scripts/test.sh`, start work.