[codex] improve developer documentation

CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to StacksOne
+
+Thank you for improving StacksOne. Keep changes focused, testable, and explicit about which layer owns the behavior.
+
+## Before starting
+
+Read:
+
+- [Development Workflow](docs/WORKFLOW.md);
+- [System Architecture](docs/SYSTEM_ARCHITECTURE.md);
+- [Contract Inventory](docs/CONTRACTS.md);
+- [Security Policy](docs/SECURITY.md).
+
+For transaction work, also read [Write Transactions](docs/WRITE_TRANSACTIONS.md).
+
+## Local setup
+
+```bash
+git clone https://github.com/bayyubenjamin/stacksone.git
+cd stacksone
+npm ci
+cp .env.example .env
+npm run dev
+```
+
+Supabase configuration is optional.
+
+Install contract-test dependencies separately:
+
+```bash
+cd smart-contracts
+npm ci
+```
+
+## Quality gates
+
+Run from the repository root:
+
+```bash
+npm test
+npm run build
+npm pack --dry-run
+```
+
+Run contract tests from `smart-contracts/`:
+
+```bash
+npm test
+```
+
+A documentation-only change should still verify that commands, paths, imports, contract identifiers, and links match the repository.
+
+## Contribution rules
+
+- Import production contract identifiers from `sdk/contracts.js`.
+- Do not hard-code deployer addresses in UI components.
+- Do not treat wallet submission as transaction confirmation.
+- Keep Supabase secondary to confirmed chain state.
+- Add tests for public SDK behavior changes.
+- Add Simnet tests for Clarity behavior changes.
+- Use versioned contract names for incompatible behavior changes.
+- Document admin roles, asset movement, post conditions, and migration impact.
+- Never commit keys, seed phrases, privileged tokens, or service-role credentials.
+
+## Pull requests
+
+A pull request should explain:
+
+- what changed;
+- why it changed;
+- affected layers;
+- user and developer impact;
+- compatibility or migration impact;
+- security assumptions;
+- checks performed;
+- deployment or release work that remains.
+
+Prefer one coherent change over a large mixture of unrelated cleanup and behavior changes.
+
+## SDK changes
+
+When changing a public export, method, normalized return shape, error class, registry key, or helper threshold:
+
+1. update tests under `tests/`;
+2. update `docs/SDK_API.md`;
+3. review semantic-version impact;
+4. inspect `npm pack --dry-run` output.
+
+## Contract changes
+
+When changing Clarity behavior:
+
+1. update or add Simnet tests;
+2. document authorization and error codes;
+3. document asset movement and post conditions;
+4. state whether the source is local-only, testnet, or configured mainnet;
+5. define the version and migration plan;
+6. do not update the runtime registry before deployment confirmation.
+
+## Security issues
+
+Do not open a public exploit report. Follow [SECURITY.md](SECURITY.md).

README.md

@@ -2,26 +2,31 @@
 
 [![CI](https://github.com/bayyubenjamin/stacksone/actions/workflows/clarinet.yaml/badge.svg)](https://github.com/bayyubenjamin/stacksone/actions/workflows/clarinet.yaml) [![npm](https://img.shields.io/npm/v/@bayybays/stacksone-sdk)](https://www.npmjs.com/package/@bayybays/stacksone-sdk) ![Stacks](https://img.shields.io/badge/network-Stacks-5546FF?logo=stacks) ![License](https://img.shields.io/badge/license-MIT-2ea44f)
 
-StacksOne is a modular identity, progression, mission, badge, token, leaderboard, and engagement layer built on Stacks. The repository contains a React reference application, the `@bayybays/stacksone-sdk` package, wallet integration, and a Clarinet smart-contract workspace.
+StacksOne is a modular identity, progression, mission, badge, token, leaderboard, reputation, and engagement layer built on Stacks. This repository contains:
 
-## Product flow
+- a React reference application;
+- the published `@bayybays/stacksone-sdk` package;
+- browser wallet and contract integrations;
+- a Clarinet workspace for the contract sources included in this repository;
+- tests and operational documentation.
+
+## What StacksOne does
+
+StacksOne gives a Stacks application a reusable progression model:
 
 ```text
 Connect wallet → read profile → complete mission → submit transaction
 → wait for confirmation → earn XP → unlock badges → build reputation
 ```
 
-Wallet request, transaction submission, and confirmed chain state are treated as separate stages. The UI keeps writes pending until the expected state can be read on-chain.
+Wallet approval, transaction submission, and confirmed on-chain state are separate stages. A wallet callback means a transaction was submitted. It does not mean the expected state change is already confirmed.
 
-## Repository
+## Requirements
 
-| Path | Purpose |
-|---|---|
-| `src/` | Home, Tasks, Vault, Profile, and Gaming UI |
-| `sdk/` | Client, contract registry, network, and value helpers |
-| `smart-contracts/` | Clarity sources, Clarinet manifest, and Simnet tests |
-| `tests/` | Public SDK behavior tests |
-| `docs/` | SDK, architecture, workflow, contract, and security notes |
+- Node.js `>=18.18`;
+- npm with lockfile support;
+- a browser Stacks wallet for interactive writes;
+- Clarinet tooling only when developing or deploying Clarity contracts.
 
 ## Quick start
 
@@ -33,49 +38,122 @@ cp .env.example .env
 npm run dev
 ```
 
-Supabase values are optional. Run quality checks with:
+The Supabase values in `.env` are optional. Leave them empty to run the wallet and on-chain features without the supporting cache layer.
+
+Run the complete repository checks:
 
 ```bash
 npm test
 npm run build
 npm pack --dry-run
-cd smart-contracts && npm ci && npm test
+
+cd smart-contracts
+npm ci
+npm test
 ```
 
-## SDK
+## SDK quick example
 
 ```js
 import { StacksOneClient } from '@bayybays/stacksone-sdk';
 
 const client = new StacksOneClient({ network: 'mainnet' });
+
 const stats = await client.getUserStats(address);
-const balance = await client.getTokenBalance(address, 'one');
+const oneBalance = await client.getTokenBalance(address, 'one');
 const taskDone = await client.isTaskDone(address, 101);
 ```
 
-Read [SDK Quick Start](docs/SDK_QUICKSTART.md) and [SDK API Reference](docs/SDK_API.md).
+The current `2.x` SDK is intentionally read-oriented. It provides normalized protocol reads, registries, helpers, and browser wallet connection. Contract writes in the reference application use `openContractCall` directly so transaction arguments, post conditions, and confirmation behavior remain explicit.
+
+Read [SDK Quick Start](docs/SDK_QUICKSTART.md), [SDK API Reference](docs/SDK_API.md), and [Write Transactions](docs/WRITE_TRANSACTIONS.md).
+
+## Repository map
+
+| Path | Purpose |
+|---|---|
+| `src/` | Reference UI for Home, Tasks, Vault, Profile, and Gaming experiences |
+| `sdk/` | Public client, canonical contract registry, network resolver, and value helpers |
+| `smart-contracts/` | Clarity sources included in this repository, Clarinet manifest, and Simnet tests |
+| `tests/` | Public SDK behavior and package-entrypoint tests |
+| `docs/` | Architecture, contract inventory, transactions, deployment, workflow, and security guidance |
+
+## Contract surfaces
+
+The runtime registry and the local Clarinet workspace serve different purposes:
+
+- `sdk/contracts.js` is the canonical application and SDK registry for configured mainnet contracts;
+- `smart-contracts/Clarinet.toml` describes only the contract sources currently included in the local Clarinet workspace;
+- a contract can be configured on mainnet without its historical source being registered in this workspace;
+- a local contract can be experimental and not yet configured for the application.
+
+Configured mainnet deployer:
+
+```text
+SP3GHKMV4GSYNA8WGBX83DACG80K1RRVQZAZMB9J3
+```
+
+Configured runtime contracts:
+
+```text
+genesis-core-v10
+genesis-missions-v10
+genesis-badges-v10
+genesis-leaderboard-v1
+genesis-boost-v1
+chaintap
+token-poin
+token-one
+```
+
+See [Contract Inventory](docs/CONTRACTS.md) for the exact local-versus-mainnet status and compatibility rules.
+
+## Architecture
+
+```text
+React reference application
+        ↓
+StacksOne SDK + canonical registry
+        ↓
+Stacks API reads + browser wallet submissions
+        ↓
+Configured Clarity contracts
+```
 
-## Configured mainnet contracts
+Confirmed on-chain records are authoritative. Supabase is optional and must remain a supporting cache or indexing layer. Frontend validation improves user experience but never replaces contract authorization.
 
-Deployer: `SP3GHKMV4GSYNA8WGBX83DACG80K1RRVQZAZMB9J3`
+See [System Architecture](docs/SYSTEM_ARCHITECTURE.md).
 
-`genesis-core-v10` · `genesis-missions-v10` · `genesis-badges-v10` · `genesis-leaderboard-v1` · `genesis-boost-v1` · `chaintap` · `token-poin` · `token-one`
+## Documentation
 
-Application code imports these identifiers from `sdk/contracts.js` to prevent configuration drift.
+| Document | Use it for |
+|---|---|
+| [SDK Quick Start](docs/SDK_QUICKSTART.md) | Installing the package and reading protocol state |
+| [SDK API Reference](docs/SDK_API.md) | Method signatures, return values, errors, and advanced injection options |
+| [Contract Inventory](docs/CONTRACTS.md) | Understanding runtime contracts and the local Clarinet workspace |
+| [Write Transactions](docs/WRITE_TRANSACTIONS.md) | Building confirmation-safe browser contract calls |
+| [Deployment Guide](docs/DEPLOYMENT.md) | Releasing contracts, registry changes, the SDK, and the frontend |
+| [Development Workflow](docs/WORKFLOW.md) | Changing code in the correct order and running quality gates |
+| [System Architecture](docs/SYSTEM_ARCHITECTURE.md) | Data ownership, module boundaries, and transaction lifecycle |
+| [Security Policy](docs/SECURITY.md) | Reporting issues, trust boundaries, and known limitations |
 
 ## Engineering principles
 
 - On-chain records remain authoritative.
 - Frontend checks do not replace contract authorization.
-- Submitted transactions remain pending until confirmed state is readable.
-- Supabase is optional and used only as a supporting layer.
-- Contract changes require explicit versioning and migration.
+- Submitted writes remain pending until confirmed state is readable.
+- Contract identifiers are imported from `sdk/contracts.js` rather than duplicated.
+- Supabase remains optional and secondary to chain state.
+- Contract logic changes require explicit versioning and migration documentation.
+- SDK behavior changes require public tests and documentation updates.
+
+## Security status
 
-See [Development Workflow](docs/WORKFLOW.md), [System Architecture](docs/SYSTEM_ARCHITECTURE.md), and [Security Policy](docs/SECURITY.md).
+StacksOne has not completed an independent third-party audit. Administrative operations still require a documented multisig process, and deployed contract logic must be replaced with a new version when behavior changes. Review [Security Policy](docs/SECURITY.md) before production integration.
 
 ## Roadmap
 
-TypeScript declarations, React hooks, richer confirmation feedback, dedicated activity views, contract-controlled mission rewards, multisig operations, migration playbooks, and expanded integration examples.
+Planned improvements include TypeScript declarations, React hooks, richer confirmation feedback, dedicated activity views, contract-controlled mission rewards, multisig operations, migration playbooks, and expanded integration examples.
 
 ## License
 

SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Do not publish an unresolved vulnerability, private key, exploit transaction, or reproducible attack path in a public issue.
+
+Use GitHub private vulnerability reporting from the repository Security tab when available. Otherwise contact the repository maintainer through the linked GitHub profile before sharing sensitive reproduction details.
+
+The full policy, supported package line, trust boundaries, current limitations, and incident-response process are documented in [docs/SECURITY.md](docs/SECURITY.md).

docs/CONTRACTS.md

@@ -0,0 +1,93 @@
+# Contract Inventory
+
+This document separates the contracts configured for the running application from the contract sources included in the local Clarinet workspace. They are related, but they are not the same inventory.
+
+## Sources of truth
+
+| Concern | Source of truth |
+|---|---|
+| Contracts used by the SDK and reference application | `sdk/contracts.js` |
+| Contract sources compiled and tested by the local Clarinet workspace | `smart-contracts/Clarinet.toml` |
+| Confirmed user state and asset ownership | The deployed Clarity contracts |
+| Optional indexed or cached data | Supabase, never authoritative |
+
+Do not infer that a mainnet contract is missing merely because its source is not registered in the current Clarinet manifest. Do not infer that a local contract is live merely because its source exists in this repository.
+
+## Configured mainnet registry
+
+The canonical runtime deployer is:
+
+```text
+SP3GHKMV4GSYNA8WGBX83DACG80K1RRVQZAZMB9J3
+```
+
+| Registry key | Contract name | Runtime role | Source registered in the current Clarinet workspace |
+|---|---|---|---|
+| `core` | `genesis-core-v10` | Profile progression, mission routing, and badge claim entrypoint used by the reference application | No |
+| `missions` | `genesis-missions-v10` | Mission completion state reads | No |
+| `badges` | `genesis-badges-v10` | Badge module identifier reserved by the runtime registry | No |
+| `leaderboard` | `genesis-leaderboard-v1` | Score and rank-tier reads | No |
+| `boost` | `genesis-boost-v1` | Progression boost module | No |
+| `chainTap` | `chaintap` | Tap-style engagement module | Yes |
+| `tokenPoin` | `token-poin` | POIN fungible-token balance reads | No |
+| `tokenOne` | `token-one` | ONE fungible-token balance reads | Yes |
+
+The SDK imports these values from `sdk/contracts.js`. Application code should import the registry instead of duplicating addresses or contract names.
+
+## Local Clarinet workspace
+
+`smart-contracts/Clarinet.toml` currently registers:
+
+| Local contract | Intended status in this repository | Configured by the runtime registry |
+|---|---|---|
+| `chaintap` | Included source with local tests and a configured mainnet counterpart | Yes |
+| `token-one` | Included source with local tests and a configured mainnet counterpart | Yes |
+| `reputation-engine` | Local contract source available for development or evaluation | No |
+
+`reputation-engine` must not be assumed to be a production dependency until it is deployed, reviewed, added to the canonical registry, documented, and covered by integration tests.
+
+## Compatibility boundaries
+
+### Application and SDK
+
+The application and SDK must resolve contract identifiers through the registry. A registry change is a runtime compatibility change and requires:
+
+1. a confirmed deployment;
+2. a review of public function and map compatibility;
+3. SDK and frontend tests;
+4. documentation updates;
+5. an explicit SDK version decision.
+
+### Contract sources
+
+Adding a contract source to the Clarinet workspace does not automatically update the production application. Removing a source from the workspace does not remove a deployed contract from the chain.
+
+### Immutable deployments
+
+Deployed Clarity logic is not edited in place. Behavioral changes require a new contract version, for example `genesis-core-v11`, followed by a controlled registry and migration update.
+
+## Mission reward trust boundary
+
+The current v10 mission interface accepts a reward argument from the caller for compatibility. The reference application derives that value from `MISSION_CATALOG`, but frontend-supplied arguments are not a security boundary. Contract authorization and contract-controlled reward state should be treated as the target design for the next mission-contract version.
+
+Until that migration is complete:
+
+- never accept an arbitrary reward value from user input;
+- derive the value from the canonical mission registry;
+- keep contract-side authorization active;
+- test duplicate completion and unauthorized-call paths;
+- monitor confirmed state rather than trusting a wallet callback.
+
+## Adding a new production contract
+
+1. Add the source and Simnet tests when the source belongs in this repository.
+2. Document admin roles, public functions, maps, tokens, and post-condition expectations.
+3. Test locally and on testnet.
+4. Complete security review and operational approval.
+5. Deploy and record the confirmed contract identifier.
+6. Add the identifier to `sdk/contracts.js`.
+7. Update SDK behavior tests and frontend integration.
+8. Update this inventory and the deployment notes.
+9. Release the SDK and frontend deliberately.
+
+See [Deployment Guide](DEPLOYMENT.md), [Write Transactions](WRITE_TRANSACTIONS.md), and [Security Policy](SECURITY.md).