InfiniteZeroFoundation · Santiagocetran · Jul 8, 2026 · Jul 11, 2026 · Jul 12, 2026 · Jul 12, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -8,6 +8,8 @@ InfiniteZero / DIN Protocol DevNet: a federated-learning network coordinated by
 
 The Solidity tree at `hardhat/contracts/` (Hardhat workflow) is used for deployment/verification tooling. 
 
+Docs convention: `Documentation/` describes what exists in the code on `develop` (not the live Sepolia deployment) — `Documentation/public/` for network participants, `Documentation/technical/` for code readers. `Developer/` holds forward-looking material: `design/` (planned mechanism designs), `issues/` (backlog), `proposals/` (tooling proposals), `tasks/` (contributor task specs), `discussion/`, `rejected-ideas/`, plus ROADMAP.md and process docs. Placement rules: `Developer/README.md`.
+
 ## Commands
 
 ### Python / dincli
@@ -44,8 +46,8 @@ dincli system connect-wallet --account <account_id>
 
 ### Two layers: protocol contracts vs. per-model task contracts
 
-- **Platform-level contracts** (deployed once by the DIN-Representative): `DinCoordinator` (ETH<->DIN exchange, slasher registry admin), `DinToken` (ERC20, minted on ETH deposit), `DinValidatorStake` (validator staking/slashing), `DinModelRegistry` (model registration, open-source vs proprietary fee). See `Documentation/DIN-workflow.md`.
-- **Task-level contracts** (deployed per model by the model owner): `DINTaskCoordinator` and `DINTaskAuditor`. These must be authorized as "slashers" on `DinValidatorStake` (via `DinCoordinator`, only callable by the DIN-Representative) *before* the model owner can register the model in `DinModelRegistry`. See `Documentation/Model-workflow.md` for the full step-by-step (deploy → slasher auth request → genesis model → register → global iterations).
+- **Platform-level contracts** (deployed once by the DIN-Representative): `DinCoordinator` (ETH<->DIN exchange, slasher registry admin), `DinToken` (ERC20, minted on ETH deposit), `DinValidatorStake` (validator staking/slashing), `DinModelRegistry` (model registration, open-source vs proprietary fee). See `Documentation/public/workflows/din-workflow.md`.
+- **Task-level contracts** (deployed per model by the model owner): `DINTaskCoordinator` and `DINTaskAuditor`. These must be authorized as "slashers" on `DinValidatorStake` (via `DinCoordinator`, only callable by the DIN-Representative) *before* the model owner can register the model in `DinModelRegistry`. See `Documentation/public/workflows/model-workflow.md` for the full step-by-step (deploy → slasher auth request → genesis model → register → global iterations).
 
 A model's lifecycle runs in **Global Iterations (GI)**: aggregator/auditor registration → Local Model Submission (LMS) by clients → auditor evaluation/scoring → two-tier aggregation (T1 sub-batches, T2 combines T1 into the new global model) → slashing of misbehaving validators → GI end. Each phase is opened/closed explicitly by the model owner via `dincli model-owner ...` subcommands, and other roles act only within an open phase.
 
@@ -64,7 +66,7 @@ Differential privacy is opt-in per model via a nested `dp` block in the manifest
 
 ### IPFS abstraction
 
-`dincli/services/ipfs.py` supports three interchangeable upload/retrieve backends (env-var-configured IPFS node, Filebase, or a fully custom Python provider) selected via `resolve_ipfs_config()`/`ipfs_provider` config — see `Documentation/guides/ipfs.md`. All CID-bearing artifacts (services, manifests, model weights, ABIs) flow through this layer rather than direct HTTP calls scattered through the CLI.
+`dincli/services/ipfs.py` supports three interchangeable upload/retrieve backends (env-var-configured IPFS node, Filebase, or a fully custom Python provider) selected via `resolve_ipfs_config()`/`ipfs_provider` config — see `Documentation/public/guides/ipfs.md`. All CID-bearing artifacts (services, manifests, model weights, ABIs) flow through this layer rather than direct HTTP calls scattered through the CLI.
 
 ### Networks
 

diff --git a/Developer/CONTRIBUTING.md b/Developer/CONTRIBUTING.md
@@ -21,6 +21,8 @@ Create a feature branch, commit your changes, and open a pull request to `develo
 
 The materials in `/Developer` are working design input, not fixed specifications. They represent current thinking, not final decisions.
 
+**Where documents live:** `Documentation/` describes what exists in the code on `develop` (`public/` for network participants, `technical/` for people modifying the code); `Developer/` holds plans, designs, proposals, tasks, and process docs. Before adding a document, read "Where does a new document go?" in [README.md](README.md).
+
 Good contributors challenge assumptions, question tradeoffs, and propose alternatives. If you see a better path, say so. The goal is the right architecture, not defending the existing one.
 
 ## Ways To Contribute

diff --git a/Developer/DEVELOPMENT_SETUP.md b/Developer/DEVELOPMENT_SETUP.md
@@ -2,7 +2,7 @@
 
 This file is the minimal setup entrypoint for contributors working on DevNet.
 
-**Prerequisite:** [Wallet Setup](../Documentation/guides/wallet-setup.md) — for development, use demo mode or `ETH_PRIVATE_KEY_<n>` in `.env`. Never commit real keys.
+**Prerequisite:** [Wallet Setup](../Documentation/public/guides/wallet-setup.md) — for development, use demo mode or `ETH_PRIVATE_KEY_<n>` in `.env`. Never commit real keys.
 
 ## Local Python Setup
 

diff --git a/Developer/GOOD_FIRST_ISSUES.md b/Developer/GOOD_FIRST_ISSUES.md
@@ -134,7 +134,7 @@ Relevant code paths:
 **Difficulty:** Intermediate → Advanced  
 **Area:** Client Services & Tooling  
 **Detailed issue:** [issues/client-data-labeling.md](issues/client-data-labeling.md)  
-**Detailed tooling:** [tooling/client-labeling.md](tooling/client-labeling.md)
+**Detailed tooling:** [tooling/client-labeling.md](proposals/client-labeling.md)
 
 Address the challenge of client-side data labeling where raw edge data is unlabeled but federated learning requires high-quality labeled datasets.
 
@@ -145,7 +145,7 @@ Current focus areas:
 
 #### Curated Review Packet
 - [Developer/issues/client-data-labeling.md](/home/azureuser/projects/devnet/Developer/issues/client-data-labeling.md)
-- [Developer/tooling/client-labeling.md](/home/azureuser/projects/devnet/Developer/tooling/client-labeling.md)
+- [Developer/proposals/client-labeling.md](/home/azureuser/projects/devnet/Developer/proposals/client-labeling.md)
 - [cache_model_0/services/client.py](/home/azureuser/projects/devnet/cache_model_0/services/client.py)
 - [dincli/services/client.py](/home/azureuser/projects/devnet/dincli/services/client.py)
 
@@ -172,5 +172,5 @@ Open a discussion or issue if you need onboarding help, architecture clarificati
 We welcome contributors from AI/ML, cryptography, distributed systems, blockchain, privacy-preserving computing, and open-source communities.
 
 [Contribution Guide →](https://github.com/InfiniteZeroFoundation/DevNet/blob/develop/Developer/CONTRIBUTING.md)  
-[Getting Started →](https://github.com/InfiniteZeroFoundation/DevNet/blob/main/Documentation/GettingStarted.md)  
+[Getting Started →](https://github.com/InfiniteZeroFoundation/DevNet/blob/develop/Documentation/public/getting-started.md)  
 [Say hello →](mailto:abrahamnash@protonmail.com)
diff --git a/Developer/README.md b/Developer/README.md
@@ -0,0 +1,31 @@
+# Developer
+
+Forward-looking material for people building the DIN Protocol: plans, designs, proposals, contributor process, and work tracking.
+
+> **Scope rule:** documents here describe **what we plan, propose, decide, or how we work** — they stay valid even as the code changes. Documentation of what currently exists on `develop` lives in [`Documentation/`](../Documentation/README.md) instead (`public/` for participants, `technical/` for people modifying the code).
+
+## Layout
+
+| Location | Contents |
+|---|---|
+| [ROADMAP.md](ROADMAP.md) | Phase plans (P2–P4) and the full work-package table with owners, dependencies, and status |
+| [`design/`](design/) | Target designs not yet (fully) implemented: [DevNet 2.0 mechanism design](design/MECHANISM_DESIGN.md), [production staking/slashing spec](design/suggested-staking-mechanism.md), [feasibility report](design/feasibility-report.md) |
+| [`issues/`](issues/) | Backlog of design/implementation write-ups per mechanism or feature (some with `design.md` / `implementation.md` / `simulation.md` subdocs) |
+| [`proposals/`](proposals/) | Tooling proposals — tools that don't exist yet (client labeling, model-owner contract/service builders) |
+| [`tasks/`](tasks/) | Contributor task specs (`task_DDMMYY_n.md`) |
+| [`discussion/`](discussion/) | Open discussions (Filecoin support, Foundry migration) |
+| [`rejected-ideas/`](rejected-ideas/) | Ideas evaluated and rejected, with rationale (e.g. TKNN-Shapley) |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution process and code standards pointers |
+| [CODE_STANDARDS.md](CODE_STANDARDS.md) | Code style and quality expectations |
+| [DEVELOPMENT_SETUP.md](DEVELOPMENT_SETUP.md) | Setting up a development environment |
+| [GOOD_FIRST_ISSUES.md](GOOD_FIRST_ISSUES.md) | Curated starter tasks for new contributors |
+
+## Where does a new document go?
+
+1. **Describes code that exists on `develop`?** → `Documentation/` (never here). Participant-facing → `Documentation/public/`; for code readers/auditors → `Documentation/technical/`.
+2. **A design or spec for something not built yet?** → `design/` (protocol mechanisms) or `proposals/` (tooling).
+3. **A backlog item someone could pick up?** → `issues/`.
+4. **A scoped task for a specific contributor?** → `tasks/`.
+5. **An open question or debate?** → `discussion/`. A decision *not* to do something → `rejected-ideas/`.
+
+**Graduation rule:** when a design from `design/` or `issues/` ships, don't move the document — write (or update) the current-state description in `Documentation/technical/` and mark the design here as shipped with a pointer. The design doc remains as the record of intent; `Documentation/` records reality. (Example: `issues/staking-mechanism.md` → `Documentation/technical/mechanisms/staking-mechanism.md`.)