test: add ARNES self-tests and docs index

docs/README.md

@@ -0,0 +1,17 @@
+# Docs index
+
+## Core docs
+- `../README.md` — framework overview
+- `../HOWTO.md` — quick start
+- `../HOWTO-FEATURE.md` — feature workflow
+- `../TEMPLATE.md` — how to adapt ARNES
+
+## Reference docs
+- `repository-layout.md` — repo structure and separation rules
+- `scripts-reference.md` — start/verify/ticket/publish/install scripts
+- `skeleton-manual.md` — default Skeleton UI notes
+
+## Harness source of truth
+- `../harness/agents.matrix.yml` — roles and edit boundaries
+- `../harness/workflow.stages.yml` — ordered workflow stages
+- `../harness/policies/` — governance, security, quality, language, model routing

docs/repository-layout.md

@@ -13,15 +13,17 @@
 - `harness/` — workflow, roles, policies, contracts
 - `spec/` — product, tech, acceptance, SDD, BDD source docs
 - `features/` — optional executable BDD runner assets
-- `scripts/` — start, verify, ticket creation, runtime status
+- `scripts/` — start, verify, ticket creation, publish, install, runtime status
 - `platforms/` — platform adapters (pi, opencode)
 - `defaults/` — optional starter assets
+- `tests/` — self-tests for the ARNES source repo only
 
 ## Recommended separation
 - Core ARNES should stay generic.
 - Domain checks go in `scripts/verify.local.sh`.
 - Domain rules go in `AGENTS.local.md`.
 - Real code should not be mixed into `harness/`, `work/`, `backlog/`, or `spec/`.
+- Source-repo self-tests under `tests/` are not part of installed project repos.
 
 ## Default project shape
 ```text

docs/scripts-reference.md

@@ -14,6 +14,8 @@ Interactive bootstrap wizard.
 What it does:
 - asks project metadata
 - chooses default app directory (`project/` by default)
+- defaults Python/Flask projects to `python3 -m unittest discover -s project/tests -v`
+- seeds a minimal bootstrap smoke test under `project/tests/` for Python/Flask
 - writes `harness/project.config.json`
 - creates `scripts/verify.local.sh`
 - can seed one bootstrap ticket
@@ -30,6 +32,7 @@ What it checks:
 - only one feature is `in_progress`
 - done features have all required artifacts, including publish evidence
 - runtime status JSON is valid
+- source-repo self-tests run automatically if `tests/` exists
 - optional local overlay runs if present
 
 ## `python3 scripts/new_ticket.py`