refactor: make ARNES external-repo based with ticket publish flow

docs/repository-layout.md

@@ -0,0 +1,38 @@
+# Repository layout
+
+## Core idea
+- ARNES core lives at repository root once installed into a project repo.
+- The source repo of ARNES is not the repo where product work should happen.
+- Real project code lives in `project/` by default.
+- Project-specific rules live in overlays, not in core files.
+
+## Main directories
+- `project/` — real app code
+- `backlog/` — ticket list and feature state
+- `work/` — runtime state, history, artifacts
+- `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
+- `platforms/` — platform adapters (pi, opencode)
+- `defaults/` — optional starter assets
+
+## 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/`.
+
+## Default project shape
+```text
+project/
+├── README.md
+├── templates/
+├── static/
+│   ├── css/
+│   ├── js/
+│   └── images/
+└── ...
+```
+
+This shape is only a default. The wizard can target another app directory if needed.

docs/scripts-reference.md

@@ -0,0 +1,66 @@
+# Scripts reference
+
+## `./scripts/install_into_repo.sh /path/to/project-repo`
+Copies ARNES core into a different project repo.
+
+What it does:
+- refuses to install into the ARNES source repo itself
+- initializes git repo at target if missing
+- copies ARNES core files into target repo
+
+## `./scripts/start.sh`
+Interactive bootstrap wizard.
+
+What it does:
+- asks project metadata
+- chooses default app directory (`project/` by default)
+- writes `harness/project.config.json`
+- creates `scripts/verify.local.sh`
+- can seed one bootstrap ticket
+- resets runtime status
+
+## `./scripts/verify.sh`
+Core harness verification.
+
+What it checks:
+- required core files exist
+- project is inside a git repo
+- warns if no git remote exists
+- backlog JSON is valid
+- only one feature is `in_progress`
+- done features have all required artifacts, including publish evidence
+- runtime status JSON is valid
+- optional local overlay runs if present
+
+## `python3 scripts/new_ticket.py`
+Interactive ticket creator.
+
+Writes one new backlog entry with:
+- `type`
+- `title`
+- `problem`
+- `goal`
+- `scope_in`
+- `scope_out`
+- `priority`
+- `risk`
+- `acceptance`
+
+## `python3 scripts/publish_ticket.py --feature-id F-001`
+Final publish step for one ticket.
+
+What it does:
+- validates git repo, remote, and git identity
+- writes `work/artifacts/<feature_id>/publish.json`
+- creates one commit for the ticket
+- pushes the branch to remote
+
+## `python3 scripts/agent_status.py`
+Runtime status helper.
+
+Commands:
+- `show`
+- `set`
+- `reset`
+
+The `set` command validates stage and agent names against harness files.