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.

.gitignore

@@ -174,3 +174,4 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+agent-tools/

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for agents working in `shard-wiki`.
+
+## Read First
+
+1. `INTENT.md` — aspiration and boundaries (stable; architectural changes are rare).
+2. `SCOPE.md` — what we are achieving now and current maturity.
+3. `.custodian-brief.md` — State Hub snapshot (generated; do not edit manually).
+
+## Documentation Layout
+
+This repo follows the CoulombSocial / HelixForge / MarkiTect documentation
+layout (recommendation, not strict law). Efficient retrieval by purpose:
+
+| Path | Purpose |
+|------|---------|
+| `INTENT.md` | Aspiration and boundaries |
+| `SCOPE.md` | Top-level view of current achievement; closes gap to INTENT |
+| `research/` | Exploration results (`yymmdd-` prefix on files or subdirs) |
+| `demand/` | Inbound requests not yet reviewed into spec or workplans |
+| `spec/` | Implementation guardrails (PRD, TSD, use cases, architecture) |
+| `workplans/` | State Hub–registered implementation tasks |
+| `docs/` | Stakeholder documentation (users, developers, humans, agents) |
+| `wiki/` | Perspective-free interconnected knowledge (wiki UI when connected) |
+| `issues/` | Mirror of relevant open tickets when ticket systems are in use |
+| `history/` | Archived material (`yymmdd-` prefix); out of scope for daily work |
+
+**Mode of operation:** close SCOPE → INTENT while learning; refine both as needed.
+
+## Domain Vocabulary
+
+Honor terms from `INTENT.md`: shard, root entity, adapter contract, projection,
+overlay, coordination journal, shard modes. Do not invent parallel vocabulary.
+
+## Build And Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check
+ruff format
+```
+
+## State Hub
+
+Workplans register with State Hub. After workplan changes:
+
+```bash
+cd ~/state-hub && make fix-consistency REPO=shard-wiki
+```
+
+Finished or canceled workplans move to `history/` with a `yymmdd-` archive prefix.
+
+## Where To Put New Material
+
+- Exploratory analysis → `research/yymmdd-<topic>/`
+- Raw feature ask or external requirement → `demand/`
+- Reviewed design ready to guide code → `spec/`
+- Implementation tasks → `workplans/`
+- User/dev/agent how-to → `docs/`
+- Collaborative unstructured notes → `wiki/`

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository status
 
-This is an **early-stage Python repository**. The package scaffold (`src/shard_wiki/`, `tests/`, `pyproject.toml`) exists with only smoke tests — the domain model is not yet implemented. Read `INTENT.md` in full before designing anything; it is the authoritative specification of what this repository is and is not. You are still establishing conventions, so keep new code consistent with the domain vocabulary below.
+This is an **early-stage Python repository**. The package scaffold (`src/shard_wiki/`, `tests/`, `pyproject.toml`) exists with only smoke tests — the domain model is not yet implemented. Read `INTENT.md` (aspiration), `SCOPE.md` (current achievement), and `AGENTS.md` (layout and conventions) before designing anything. Close the gap from SCOPE to INTENT via `research/`, `spec/`, and `workplans/`.
 
 ## What this project is
 

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)
+```

SCOPE.md

@@ -0,0 +1,57 @@
+# SCOPE
+
+## One-Liner
+
+Git-based Markdown wiki orchestrator and federation layer — early-stage scaffold
+with intent, research, and specification groundwork; domain model not yet
+implemented.
+
+## Mode Of Operation
+
+Close the gap between this file and `INTENT.md` by exploring the problem space
+(`research/`), reviewing inbound demand (`demand/`), refining specifications
+(`spec/`), and implementing through registered workplans (`workplans/`).
+Learnings update both SCOPE and INTENT where necessary.
+
+## Current Status
+
+| Layer | State |
+|-------|-------|
+| Code | Python package scaffold (`src/shard_wiki/`, smoke tests only) |
+| Intent | `INTENT.md` established; authorization-in-core amendments drafted |
+| Research | yawex prior-art exploration (`research/260608-yawex-prior-art/`) |
+| Demand | NetKingdom integration asks captured, not yet negotiated |
+| Spec | Access/history architecture blueprint drafted; PRD/TSD/UCC scaffolds |
+| Work | `SHARD-WP-0001` active — 6 design tasks, all todo |
+
+## In Scope (today)
+
+- Establishing repository documentation structure and specification groundwork.
+- Federation design informed by yawex prior art (page resolution, namespaces,
+  derived views, provenance, overlays).
+- Authorization model design (delegated authentication, core authorization).
+- Shard adapter contract and wiki page model (to be specified, then implemented).
+- Git-backed coordination journal for information spaces.
+- State Hub workplan registration and consistency sync.
+
+## Out Of Scope (today)
+
+- A standalone wiki engine UI or rendering pipeline.
+- Authentication, credential storage, or user directory implementation.
+- Hard-coded editorial, sync, or conflict-resolution policy.
+- Generic file mirroring independent of wiki-page semantics.
+- Production deployment, multi-tenant operations, or enterprise IAM rollout.
+
+## Boundary Rule
+
+`shard-wiki` orchestrates wiki-shaped content across heterogeneous shards. It
+provides mechanisms (federation, projection, overlay, patching, reconciliation);
+policy (canonical source, conflict preference, access rules) remains explicit and
+configurable. Identity comes from pluggable providers; authorization decisions
+live in core.
+
+## Current Planning
+
+Design work is tracked in `workplans/SHARD-WP-0001-yawex-requirements.md`.
+Specification outputs from that workplan land in `spec/`. Inbound integration
+asks remain in `demand/` until reviewed and promoted into spec or workplans.

demand/260608-netkingdom-integration-requirements.md

@@ -1,8 +1,10 @@
 # Requirements — what shard-wiki needs from user-engine & net-kingdom
 
-Status: **draft for review** · Date: 2026-06-08
+Status: **inbound demand — draft for review** · Date: 2026-06-08
 
-Derived from `access-model-blueprint.md`. These are the integration contracts shard-wiki
+Located in `demand/` — not yet promoted to `spec/` or workplans.
+
+Derived from `spec/ArchitectureBlueprint.md`. These are the integration contracts shard-wiki
 needs to climb from L0 (open, standalone) to L4 (multi-tenant enterprise) **without
 changing its core**. They are requirements *on* the NetKingdom domain repos, to be
 negotiated with their owners — not assumptions about their current implementation.

demand/README.md

@@ -0,0 +1,13 @@
+# demand/
+
+Inbound feature requests, requirements, suggestions, and improvement
+opportunities that have **not** been systematically reviewed and captured in
+`spec/` or `workplans/`.
+
+Material here may be raw and needs scrutiny before implementation picks it up.
+
+## Current Items
+
+| Date | File | Summary |
+|------|------|---------|
+| 2026-06-08 | `260608-netkingdom-integration-requirements.md` | Integration contracts needed from user-engine and net-kingdom for L2–L4 access modes |

docs/README.md

@@ -0,0 +1,14 @@
+# docs/
+
+Stakeholder-facing documentation for users, developers, humans, and agents.
+
+Rewrite docs when they become wrong or stale — they should reflect what the
+repo actually does.
+
+| Document | Audience |
+|----------|----------|
+| `repository-layout.md` | All — how documentation is organized in this repo |
+| `../README.md` | New visitors — project entry point |
+| `../AGENTS.md` | Agents — working conventions and layout |
+| `../INTENT.md` | Architects — aspiration and boundaries |
+| `../SCOPE.md` | Contributors — current achievement and planning |

docs/repository-layout.md

@@ -0,0 +1,58 @@
+# Repository documentation layout
+
+This repository follows the CoulombSocial / HelixForge / MarkiTect documentation
+layout. It is a **recommendation** for efficient information retrieval, not a
+strict law.
+
+## Operating model
+
+- `INTENT.md` captures aspiration and boundaries.
+- `SCOPE.md` captures a top-level view of what we achieve.
+- Work closes the gap from SCOPE to INTENT while learning and refining both.
+
+## Directories
+
+### `research/`
+
+Exploration results in the problem and solution space. Use a `yymmdd-` prefix
+on markdown files or subdirectories when multiple files or sources are involved.
+
+### `demand/`
+
+Inbound feature requests, requirements, and suggestions not yet reviewed into
+`spec/` or `workplans/`. Raw material — needs scrutiny before implementation.
+
+### `spec/`
+
+Implementation guardrails. Typical files:
+
+- `ProductRequirementsDocument.md`
+- `TechnicalSpecificationDocument.md`
+- `UseCaseCatalog.md`
+- `ArchitectureBlueprint.md`
+
+Background: InfoTechPrimers on coulomb.social.
+
+### `workplans/`
+
+State Hub–registered workplans with implementation tasks. Finished or canceled
+workplans move to `history/` with a `yymmdd-` archive prefix.
+
+### `docs/`
+
+Stakeholder documentation (this directory).
+
+### `wiki/`
+
+Interconnected collective knowledge without a single perspective. Powerful when
+connected to a wiki UI for creators, users, and investors.
+
+### `issues/`
+
+Optional mirror of relevant open tickets from customer support, dev-sec-ops, or
+other ticket systems.
+
+### `history/`
+
+Archived material no longer needed for daily work. Use `yymmdd-` prefixes.
+Consult only for research or diagnostics.

history/README.md

@@ -0,0 +1,8 @@
+# history/
+
+Archived material that is no longer needed for daily work but should be kept.
+
+Use a `yymmdd-` prefix when archiving files or directories. Content here is
+**out of scope** for regular tasks — consult only for research or diagnostics.
+
+Finished or canceled workplans from `workplans/` are archived here.

issues/README.md

@@ -0,0 +1,7 @@
+# issues/
+
+Optional mirror of relevant open tickets from customer support, dev-sec-ops, or
+other work-organization systems.
+
+No mirrored issues yet. When ticket systems are in use, copy or link relevant
+open items here for easier repository-local access.

research/260608-yawex-prior-art/README.md

@@ -0,0 +1,19 @@
+# 260608 — yawex prior art exploration
+
+Date: 2026-06-08
+
+## What this is
+
+Review of **yawex 0.7.4** (2004–05 filesystem-backed CGI/Perl wiki engine) as
+prior art for `shard-wiki` federation design.
+
+## Contents
+
+| Path | Role |
+|------|------|
+| `findings.md` | Distilled KEEP / TRANSFORM / DROP analysis and open questions |
+| `sources/yawex-0.7.4/` | Original prior-art tree (Perl engine, pages, templates) |
+
+## Status
+
+Exploration complete. Design tasks tracked in `workplans/SHARD-WP-0001`.

research/260608-yawex-prior-art/findings.md

@@ -1,6 +1,6 @@
 # Requirements seed — review of yawex prior art
 
-Source: `history/priorart/yawex-0.7.4/` — a filesystem-backed CGI/Perl wiki engine
+Source: `research/260608-yawex-prior-art/sources/yawex-0.7.4/` — a filesystem-backed CGI/Perl wiki engine
 (2004–2005, "Yet Another Wiki engine eXtended"). This document distills that prior
 art into requirements for `shard-wiki`, the Markdown-first, Git-backed wiki
 **federation/orchestration layer** described in `INTENT.md`.

research/README.md

@@ -0,0 +1,13 @@
+# research/
+
+Exploration results for the problem and solution space.
+
+Each exploration uses a `yymmdd-` prefix on the markdown file or subdirectory
+when multiple files or sources are involved. Findings here inform `spec/` and
+`SCOPE.md`; they do not directly authorize implementation until promoted.
+
+## Active Explorations
+
+| Date | Path | Summary |
+|------|------|---------|
+| 2026-06-08 | `260608-yawex-prior-art/` | yawex 0.7.4 Perl wiki prior art; federation design seeds |

spec/ArchitectureBlueprint.md

@@ -1,8 +1,11 @@
-# Architecture blueprint — shard-wiki access & history model
+# ArchitectureBlueprint — shard-wiki access & history model
 
 Status: **draft for review** · Date: 2026-06-08 · Resolves pending decision
 "Scope of a minimal access model in shard-wiki core".
 
+Part of `spec/`. Background on specification document types: InfoTechPrimers on
+coulomb.social.
+
 This blueprint settles how shard-wiki handles access control and change history. It
 realizes the INTENT principles *Open by default, progressively governed*, *History as
 the safety net*, and *Authorization in core, authentication delegated*.
@@ -142,4 +145,5 @@ identical; only the gate differs.
 4. How tenant ↔ root-entity mapping is configured and discovered.
 5. Whether L1 "attributed but open" is worth shipping or we jump L0 → L2.
 
-See `requirements-user-engine-netkingdom.md` for the concrete asks these imply.
+See `demand/260608-netkingdom-integration-requirements.md` for the concrete asks
+these imply.

spec/ProductRequirementsDocument.md

@@ -0,0 +1,54 @@
+# ProductRequirementsDocument
+
+Status: **draft scaffold** · Date: 2026-06-08
+
+See InfoTechPrimers on coulomb.social for PRD conventions.
+
+## 1. Product Name
+
+**shard-wiki**
+
+## 2. Product Intent
+
+Git-based Markdown wiki **orchestrator and federation layer** — not a wiki
+engine. Joins heterogeneous wiki-shaped page stores (shards) into a coherent
+information space while preserving provenance, capabilities, and history.
+
+Authoritative aspiration: `INTENT.md`.
+
+## 3. Problem Statement
+
+Wiki content lives in fragmented backends (Git repos, Gitea wikis, local
+folders, Obsidian vaults, WebDAV, application databases). Users and tools need a
+union of pages with versionable coordination, overlays for remote edits, and
+explicit provenance — without forcing a single storage format or engine.
+
+## 4. Target Users
+
+See `INTENT.md` § Intended Users.
+
+## 5. Core Capabilities (maturity target)
+
+- Attach multiple shards to a shared root entity.
+- Present union views of pages, links, metadata, and revisions.
+- Lazy projection and cache of remote shard content.
+- Overlay-before-mutation for capability-limited shards.
+- Git-backed coordination journal per information space.
+- Capability-aware shard adapter contract.
+- Pluggable authorization from open (L0) through multi-tenant enterprise (L4).
+- Complete recoverable history as the baseline safety net.
+
+## 6. Non-Goals
+
+See `INTENT.md` § Strategic Boundaries.
+
+## 7. Research Inputs
+
+- `research/260608-yawex-prior-art/findings.md` — federation design seeds from
+  prior art.
+
+## 8. Open Items
+
+Pending completion of `SHARD-WP-0001` design tasks and ratification of access
+model INTENT amendments. Detailed requirements will be expanded as spec tasks
+complete.

spec/README.md

@@ -0,0 +1,15 @@
+# spec/
+
+Specification files that guide and guardrail implementation.
+
+Background on document types: InfoTechPrimers on coulomb.social.
+
+| File | Status | Role |
+|------|--------|------|
+| `ProductRequirementsDocument.md` | draft scaffold | What the product must deliver |
+| `TechnicalSpecificationDocument.md` | draft scaffold | How the system is built |
+| `UseCaseCatalog.md` | draft scaffold | Observable usage scenarios |
+| `ArchitectureBlueprint.md` | draft | Access, history, and identity architecture |
+
+Promote material from `research/` and reviewed items from `demand/` into spec
+before treating it as implementation authority.

spec/TechnicalSpecificationDocument.md

@@ -0,0 +1,51 @@
+# TechnicalSpecificationDocument
+
+Status: **draft scaffold** · Date: 2026-06-08
+
+See InfoTechPrimers on coulomb.social for TSD conventions.
+
+## 1. System Overview
+
+Python package (`src/shard_wiki/`) implementing a federation orchestration
+layer. Markdown-first, backend-neutral page model. Git-addressable coordination
+per information space.
+
+## 2. Implementation Stack
+
+| Concern | Choice |
+|---------|--------|
+| Language | Python ≥ 3.11 |
+| Layout | `src/` package, hatchling build |
+| Tests | pytest |
+| Lint/format | ruff |
+
+## 3. Core Abstractions (to be specified)
+
+| Abstraction | Description |
+|-------------|-------------|
+| Shard | Independently meaningful page store with sovereignty |
+| Root entity | Joined information space shards attach to |
+| Shard adapter contract | Versioned, capability-aware backend interface |
+| Wiki page model | Paths, links, metadata, revisions |
+| Projection | Lazy local view of remote content |
+| Overlay | Non-destructive edit before remote mutation |
+| Coordination journal | Git-backed change record |
+
+## 4. Architecture References
+
+- `spec/ArchitectureBlueprint.md` — access, history, identity delegation
+
+## 5. Integration Boundaries
+
+- Authentication delegated to external identity provider (reference:
+  net-kingdom + user-engine). See `demand/260608-netkingdom-integration-requirements.md`.
+- No credential or secret storage in shard-wiki core.
+
+## 6. Current Implementation
+
+Package scaffold only (`__version__`, smoke tests). Domain model not yet coded.
+
+## 7. Next Specification Work
+
+Outputs from `SHARD-WP-0001` tasks (page resolution, namespaces, derived views,
+provenance, overlays, link semantics) will be incorporated here as they complete.

spec/UseCaseCatalog.md

@@ -0,0 +1,47 @@
+# UseCaseCatalog
+
+Status: **draft scaffold** · Date: 2026-06-08
+
+See InfoTechPrimers on coulomb.social for use-case catalog conventions.
+
+## UC-01 — Standalone open wiki (L0)
+
+**Actor:** Anonymous contributor  
+**Goal:** Read and write wiki pages with full history and no external dependencies.  
+**Notes:** Ward Cunningham / c2-style open mode. Recovery via Git history, not gatekeeping.
+
+## UC-02 — Attach a Git repo shard
+
+**Actor:** Maintainer  
+**Goal:** Attach a repository or `wiki/` subdirectory as a shard of an information space.  
+**Notes:** Preserve shard sovereignty and adapter capability profile.
+
+## UC-03 — Project a remote shard page locally
+
+**Actor:** Reader  
+**Goal:** View a page from a remote or read-only shard as a local projection with provenance and freshness visible.  
+**Notes:** Lazy projection; no silent mutation.
+
+## UC-04 — Overlay edit on read-only shard
+
+**Actor:** Author  
+**Goal:** Propose changes to a remote/read-only page as overlay/draft/patch before destructive apply.  
+**Notes:** Overlay-before-mutation principle.
+
+## UC-05 — Union browse (BackLinks, RecentChanges)
+
+**Actor:** Reader  
+**Goal:** Navigate derived views across all attached shards.  
+**Notes:** BackLinks over federated link graph is a strong core candidate (see research findings).
+
+## UC-06 — Authenticated team wiki (L2+)
+
+**Actor:** Authenticated principal  
+**Goal:** Read/write under role-based authorization with identity from external provider.  
+**Notes:** See `spec/ArchitectureBlueprint.md` capability ladder.
+
+## UC-07 — Detect cross-shard divergence
+
+**Actor:** Maintainer  
+**Goal:** Identify when equivalent pages in different shards have diverged and reconcile.  
+**Notes:** Union without erasure — conflicts visible, not hidden.

wiki/README.md

@@ -0,0 +1,7 @@
+# wiki/
+
+Perspective-free interconnected knowledge for this repository.
+
+This directory is intended for collaborative wiki content when a wiki UI is
+connected. Until then, use `docs/` for stakeholder-facing documentation and
+`research/` for structured explorations.

workplans/SHARD-WP-0001-yawex-requirements.md

@@ -22,10 +22,10 @@ that map onto `INTENT.md` without inheriting yawex's monolithic engine shape.
 
 ## Context
 
-- Prior art: `history/priorart/yawex-0.7.4/`
+- Prior art: `research/260608-yawex-prior-art/sources/yawex-0.7.4/`
-- Requirements seed: `docs/requirements-from-yawex.md`
+- Research findings: `research/260608-yawex-prior-art/findings.md`
-- Access model draft: `docs/access-model-blueprint.md`
+- Architecture: `spec/ArchitectureBlueprint.md`
-- NetKingdom integration draft: `docs/requirements-user-engine-netkingdom.md`
+- Inbound demand: `demand/260608-netkingdom-integration-requirements.md`
 
 Open architectural thread: a minimal authorization model in core revises an
 INTENT non-goal and needs a ratified INTENT amendment before the access model
@@ -111,7 +111,7 @@ red-link extension. Open question: core vs reference-UI concern.
 
 ## Acceptance criteria
 
-- Each task produces a written spec or ADR-ready design note in `docs/`.
+- Each task produces a written spec or ADR-ready design note in `spec/`.
 - Designs honor INTENT boundaries: mechanism over policy, union without erasure,
   overlay before mutation, capability-aware adapters.
 - Access-model and NetKingdom integration drafts are either ratified or explicitly