RuneLabsxyz · 0xMugen · Feb 26, 2026 · Feb 26, 2026
diff --git a/README.md b/README.md
@@ -1,101 +1,107 @@
-# PonziLand Guilds Specifications (v0.1)
+#
+#  ____       _ _     _     _      
+# / ___|_   _(_) | __| |___| |__   
+#| |  _| | | | | |/ _` / __| '_ \  
+#| |_| | |_| | | | (_| \__ \ | | | 
+# \____|\__,_|_|_|\__,_|___/_| |_| 
+#
 
-Welcome to the **PonziLand Guilds** module—designed to introduce social, political, and economic dynamics through onchain guilds.
+# Guilds
 
----
+Guilds is a contract-first Starknet system for on-chain guild governance, treasury operations, and dual revenue distribution (members + shareholders).
 
-## 🔗 Quick Links
+## Architecture
 
-- **Website:** https://www.ponzi.land  
-- **Runelabs:** https://www.runelabs.xyz  
-- **Discord:** https://discord.gg/ponziland  
-- **Twitter (PonziDotLand):** https://x.com/ponzidotland  
-- **Twitter (RuneLabsxyz):** https://x.com/runelabsxyz
+- `src/guild/guild_contract.cairo`: guild core state machine (membership, roles, treasury, revenue, shares)
+- `src/token/guild_token.cairo`: ERC20Votes-style guild token with inactivity handling
+- `src/governor/guild_governor.cairo`: governance control plane
+- `src/models/*`: canonical structs, constants, and events
+- `tests/*.cairo`: unit + integration-style coverage by domain
+- `sdk/`: typed TypeScript SDK with compatibility gate and smoke tests
 
----
+## Quickstart
 
-## 🎯 Objectives
+### Contracts
 
-1. **Facilitate social community formation** inside the game
-2. **Introduce competitive and political narratives** via guild dynamics
-3. **Enable economic access and mobility** for smaller or new players
-4. **Support team-based esports** with in‑game guild competitions
+```bash
+# Option A: use your existing local Scarb/Snforge install
+scarb fmt --check --workspace
+snforge test
 
-*Guilds function as a DAO, an investment fund, and an esports team.*
+# Option B: project verify fallback
+bash -lc 'sozo test || scarb test'
+```
 
----
+### SDK
 
-## 🛠️ Basic Features
+```bash
+cd sdk
+npm install
+npm run verify
+```
 
-### Creating a Guild
+## Deployment / Stack Flow
 
-- **Capital requirement:** Player must deposit a minimum capital (e.g. $10) at creation.
-  - 1000 shares are minted; initial share value = capital / 1000.
-- **Metadata:**
-  - **Logo:** Generated via in‑game pattern designer and minted on-chain.
-  - **Guild name:** 4–50 chars; letters, numbers, spaces, dots; unique among active guilds.
-  - **Ticker:** 1–5 chars; letters, numbers, spaces, dots; globally unique.
-  - **Description:** Up to 4,000 characters (editable).
-- **Governance settings:** Default profit distribution and role‑based rules set by CEO at creation.
+Guilds uses Graphite stack workflows for incremental contract delivery.
 
-### Closing a Guild
+```bash
+gt create -m "feat(guilds): <scope>"
+gt restack --upstack --no-interactive
+gt submit --stack --no-interactive
+```
 
-- All members must leave or be removed.
-- CEO must resign to trigger on-chain guild closure.
-- A liquidation has been voted.
+Operator scripts:
 
-### Joining a Guild
+- `scripts/operator/repair-graphite-stack.sh`: detects/tracks untracked branches, restacks with fallback
+- `scripts/operator/qa-self-heal.sh`: verify-loop with deduplicated failure task generation
 
-| Type           | Behavior                                                                                     |
-| -------------- | -------------------------------------------------------------------------------------------- |
-| **Public**     | Instant join; optional soft filters (level, experience).                                     |
-| **Private**    | Players submit join request with optional message.                                           |
-| **Invitation** | Officers send direct invites; bypass request queue.                                          |
-| **Management** | Officers can approve, reject, or blacklist; Master toggles recruitment status.               |
+## Test & Verify Flow
 
-### Player Management
+- Contracts: `scarb fmt --check --workspace && snforge test`
+- Fallback verify: `sozo test || scarb test`
+- SDK type + compat + tests + build: `cd sdk && npm run verify`
 
-- **Roles & Permissions:** Kick, ban, promote/demote
-- **Request Handling:** Approve, reject, blacklist
+## SDK (TS, Production-Oriented)
 
-### Season Scoring & Standings
+Package: `@runelabsxyz/guilds-sdk`
 
-Track guild performance metrics each season:
+- Typed client API (`core/client/types/utils/errors/config/bindings`)
+- Contract compatibility gate via `sdk/generated/contracts.signature.json`
+- Deterministic error model (`GuildsSdkError` with fixed error codes)
+- Retry support for transport operations
+- Example flows in `sdk/examples/`
 
-- Sum of player scores
-- Total land owned & assets
-- Stakes and supply metrics
-- Leaderboard positions
+Common flows:
 
----
+1. Create guild
+2. Register/wire addresses
+3. Governance action + vote
+4. Treasury and token/share operations
 
-## 💰 Economic Structure
+## Security Notes
 
-Guilds manage shared capital via an on-chain share system:
+- Governor-only and permission-gated boundaries enforced in guild logic
+- Explicit numeric bound checks (BPS sums, plugin action ranges)
+- Deterministic panic/error paths for negative scenarios
+- Event coverage for indexers (`src/models/events.cairo`)
 
-1. **Capital Building:** CEO deposits base capital; 1000 ERC‑20 shares minted.
-2. **Shareholding:** Players buy shares via on-chain rounds.
-3. **Voting:** Share count = voting power; used for share emissions and rate changes.
-4. **Emitting Shares:** 51% shareholder approval; public purchase round with proportional allocation.
+See `docs/CONTRACT-GUIDELINES-CHECKLIST.md` for itemized evidence.
 
-### Capital Distribution & Yield
+## Roadmap & Status
 
-- Guild owns a portfolio of tokens as idle capital.
-- Objective: maximize ROI by allocating to productive players.
+- Completed: data model, permissions, lifecycle, token, governor, treasury, revenue
+- Completed: SDK productization and operator automation
+- Stack integration pending: Graphite stack submit + merge
 
----
+Vault coverage is tracked in `docs/VAULT-COVERAGE.md`.
 
-## 🏛️ Guild Roles & Wallets
+## Release Notes Surface
 
-| Role           | Description                                                                                       |
-| -------------- | ------------------------------------------------------------------------------------------------- |
-| **Guild Master** | Elected CEO; sole issuer of major proposals; controls master wallet.                             |
-| **Co‑Leader**    | Second‑in‑command; assists Master; accesses high‑tier wallet.                                   |
-| **Officer**      | Manages membership, requests; accesses mid‑tier wallet.                                        |
-| **Member**       | Standard participant; accesses member wallet.                                                  |
-| **Recruit**      | Trial role; limited permissions; no wallet access.                                            |
+- Release readiness: `docs/RELEASE-READINESS.md`
+- SDK changelog: `sdk/CHANGELOG.md`
+- Contract spec: `docs/SPEC.md`
 
-- **Guild Wallets:** Five on-chain wallets, each gated by role for capital allocation and payouts.
+## License
 
 ---
 

diff --git a/docs/CONTRACT-GUIDELINES-CHECKLIST.md b/docs/CONTRACT-GUIDELINES-CHECKLIST.md
@@ -0,0 +1,20 @@
+# Contract Guidelines Checklist
+
+| Guideline Item | Pass/Fail | Evidence (File/Test/Commit) | Remediation PR |
+| --- | --- | --- | --- |
+| Access control boundaries on privileged paths | Pass | `src/guild/guild_contract.cairo` (`_only_governor`, `_check_permission`), `tests/test_permissions.cairo`, commit `dd5f53d` | - |
+| Initialization safety (single init assumptions) | Pass | `src/guild/guild_contract.cairo` initialization wiring, `src/token/guild_token.cairo` constructor wiring, `tests/test_lifecycle.cairo` | - |
+| Duplicate entrypoint prevention | Pass | Interface split in `src/interfaces/*.cairo`, contracts compile target in `Scarb.toml`, CI workflow `.github/workflows/_test-contracts.yaml` | - |
+| Storage read/write trait correctness | Pass | `starknet::Store` derivations in `src/models/types.cairo`, storage read/write patterns in `src/guild/guild_contract.cairo`, `src/token/guild_token.cairo` | - |
+| Assert/message conventions compatible with toolchain | Pass | Felt-based error constants in `src/guild/guild_contract.cairo` (`mod Errors`), negative-path tests in `tests/test_*` | - |
+| Numeric bounds / felt range safety | Pass | Action bounds checks in `src/guild/guild_contract.cairo` (plugin offset overflow and BPS sum checks), tests in `tests/test_revenue.cairo` | - |
+| Deterministic error paths | Pass | Centralized error constants in `src/guild/guild_contract.cairo`, `#[should_panic]` assertions across tests | - |
+| Invariant preservation under edge cases | Pass | Lifecycle, treasury, token inactivity, and revenue edge cases in `tests/test_lifecycle.cairo`, `tests/test_treasury.cairo`, `tests/test_guild_token.cairo`, `tests/test_revenue.cairo` | - |
+| Event emissions for indexability | Pass | Event models in `src/models/events.cairo`, emission points in `src/guild/guild_contract.cairo`, tests covering state transitions | - |
+| Factory lifecycle implementation completeness | Pass | Implementation at `src/factory/guild_factory.cairo`, exports in `src/lib.cairo`, coverage in `tests/test_factory.cairo`, commit `5b6fd20` | - |
+
+## Notes
+
+- This checklist is release-gating documentation.
+- A `Fail` item blocks final production-go unless explicitly accepted as a limitation.
+- If a new contract/security guideline is introduced, add a new row with evidence before merge.
diff --git a/docs/RELEASE-READINESS.md b/docs/RELEASE-READINESS.md
@@ -0,0 +1,48 @@
+# Release Readiness Report
+
+## Checklist
+
+- [x] Graphite stack repair and operator scripts added (`scripts/operator/repair-graphite-stack.sh`, `46ef136`)
+- [x] QA self-heal loop added (`scripts/operator/qa-self-heal.sh`, `46ef136`)
+- [x] Contract test workflow exists (`.github/workflows/_test-contracts.yaml`, `46ef136`)
+- [x] SDK scaffold implemented (`sdk/`, `7b6cb98`, `f2f56c9`)
+- [x] Vault coverage matrix added (`docs/VAULT-COVERAGE.md`)
+- [x] Contract guidelines checklist added (`docs/CONTRACT-GUIDELINES-CHECKLIST.md`)
+- [x] Factory lifecycle implementation completed (`src/factory/guild_factory.cairo`, `tests/test_factory.cairo`, `5b6fd20`)
+
+## Known Limitations
+
+1. Local environment must provide Scarb/Snforge/USC toolchain (or Nix shells + binaries) for deterministic contract verification.
+
+## Migration Notes
+
+- Existing contracts follow v0.2 data model and permission boundaries (`5060c00`, `dd5f53d`, `f862363`, `91607db`, `b58d212`, `486b922`, `2370af8`).
+- SDK introduces compatibility checks against Cairo interface signatures (`sdk/generated/contracts.signature.json`).
+- Any interface changes now require `npm run sync:contracts` in `sdk/`.
+
+## Test Matrix (Current)
+
+| Scope | Command | Expected Result |
+| --- | --- | --- |
+| Cairo fmt + test | `scarb fmt --check --workspace && snforge test` | pass |
+| Fallback verify | `sozo test || scarb test` | pass |
+| SDK type checks | `npm run typecheck && npm run typecheck:examples` (in `sdk/`) | pass |
+| SDK compatibility gate | `npm run check:compat` (in `sdk/`) | pass |
+| SDK tests | `npm run test` (in `sdk/`) | pass |
+
+## Operator Mode
+
+Run from repo root:
+
+```bash
+./scripts/operator/repair-graphite-stack.sh
+./scripts/operator/qa-self-heal.sh
+```
+
+- `repair-graphite-stack.sh` tracks untracked branches, restacks iteratively, and clears metadata cache as fallback.
+- `qa-self-heal.sh` loops verify, creates deduplicated fix tasks in `.operator/tasks/`, and exits green only when verify passes.
+
+## Go/No-Go
+
+- **Current recommendation:** **GO** after stack submit/merge and one final CI green pass.
+- **Hardening window (next 7 days):** reduce deprecated `contract_address_const` usage warnings and remove stale unused imports in legacy modules.
diff --git a/docs/VAULT-COVERAGE.md b/docs/VAULT-COVERAGE.md
@@ -0,0 +1,18 @@
+# Vault Coverage Matrix
+
+Canonical requirement source: `/home/mugen/Documents/Obsidian Vault/life/areas/projects/guilds.md`.
+
+| Vault Requirement | Task/PR | Status | Test Coverage | Merged Commit |
+| --- | --- | --- | --- | --- |
+| Governance-first delegation model | `feat/guild-lifecycle`, `feat/governor`, `feat/permission-system` | Implemented | `tests/test_lifecycle.cairo`, `tests/test_guild_governor.cairo`, `tests/test_permissions.cairo` | `f862363`, `b58d212`, `dd5f53d` |
+| Role framework and bypass boundaries | `feat/permission-system` | Implemented | `tests/test_permissions.cairo`, `tests/test_lifecycle.cairo` | `dd5f53d`, `f862363` |
+| Share lifecycle and inactivity handling | `feat/guild-token`, `feat/revenue` | Implemented | `tests/test_guild_token.cairo`, `tests/test_revenue.cairo` | `91607db`, `2370af8` |
+| Dual revenue model (shareholder + member) | `feat/revenue` | Implemented | `tests/test_revenue.cairo` | `2370af8` |
+| End-to-end governance to execution paths | `feat/governor`, `feat/treasury`, `feat(factory)` | Implemented | `tests/test_guild_governor.cairo`, `tests/test_treasury.cairo`, `tests/test_factory.cairo` | `b58d212`, `486b922`, `5b6fd20` |
+| SDK v0 scaffold after contract hardening | `feat(sdk): production scaffold` | Implemented | `sdk/tests/address.test.ts`, `sdk/tests/retry.test.ts`, `sdk/tests/client.smoke.test.ts` | `7b6cb98`, `f2f56c9` |
+
+## Coverage Notes
+
+- Local stack commits listed above become merge commits after stack submission.
+- This matrix must be updated in every cycle that changes contracts, SDK interfaces, or vault requirements.
+- SDK compatibility gate is enforced by `sdk/scripts/check-contract-compat.mjs` and snapshot file `sdk/generated/contracts.signature.json`.