Reorganize documentation into canonical repository layout

Adopt CoulombSocial/HelixForge/MarkiTect documentation structure:
- research/260608-yawex-prior-art/ — yawex exploration and sources
- demand/ — inbound NetKingdom integration requirements
- spec/ — PRD, TSD, UseCaseCatalog, ArchitectureBlueprint scaffolds
- docs/ — stakeholder documentation and repository-layout guide
- wiki/, issues/, history/ — scaffolded directories

Add SCOPE.md and AGENTS.md. Update workplan paths and README.

README.md

@@ -1,2 +1,41 @@
-Git based markdown wiki orchestrator
+# shard-wiki
 
+Git-based Markdown wiki orchestrator and federation layer.
+
+`shard-wiki` joins heterogeneous wiki-shaped page stores (**shards**) into a
+coherent information space while preserving provenance, capabilities, and
+history. It is an orchestration layer, not a wiki engine.
+
+## Status
+
+Early-stage: Python scaffold, intent and specification groundwork, active design
+workplan. See `SCOPE.md` for current maturity.
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [INTENT.md](INTENT.md) | Aspiration and boundaries |
+| [SCOPE.md](SCOPE.md) | What we achieve now |
+| [AGENTS.md](AGENTS.md) | Agent working guide |
+| [docs/repository-layout.md](docs/repository-layout.md) | How this repo organizes information |
+
+## Quick start
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Layout
+
+```
+research/     explorations (yymmdd-prefixed)
+demand/       inbound unreviewed requirements
+spec/         implementation specifications
+workplans/    State Hub–registered tasks
+docs/         stakeholder documentation
+wiki/         collaborative knowledge (wiki UI when connected)
+issues/       ticket mirrors
+history/      archived material (yymmdd-prefixed)
+```