docs: organize AgentShack README and repository guides

[jh1nresh]

Product Outcome

Make the public repository understandable without mixing the current BNB marketplace, retained Maiat Dojo APIs and historical concepts. Documentation maintenance; demand/pricing N/A. Distribution: repository README and docs.

Changes

• Replace the old Maiat Dojo pitch with a concise AgentShack overview, four bounded services, testnet boundaries, current navigation and repository map.
• Add a docs index, PostgreSQL/Privy development guide and separate workflow integration guide.
• Add a localhost-only .env.example; keep real environment files ignored. Remove destructive seeding from the default setup sequence and document the existing seed's deletion behavior.
• Move the old root spec index into docs/archive/, preserve original Base contract notes there, and replace the contract entry point with current source boundaries and pinned read-only verification instructions.
• Mark fixture-based design screenshots historical, update the same-browser recovery description and replace maintainer-specific MCP paths/unverified npm-install assumptions with local usage.
• Preserve compatibility names, both lockfiles, operational scripts and tracked specifications. Flag legacy Makefile broadcast targets rather than silently changing operational behavior.

State And Trust Boundary

No app/API, database schema, auth/payment, Solidity, dependency, CI, deployment or repository-setting changes. No real credentials copied. User-owned dirty AGENTS.md and PR #5 preserved. No seed, schema push, broadcast or real-wallet call executed.

Verification

• Focused static checker: 11 changed/new Markdown files, 89 local links/anchors, balanced code fences — passed.
• npm-script and PostgreSQL provider cross-check against package.json/schema; blank Privy fields and localhost-only example DB — passed.
• Ignore checks: .env, .env.local, .env.production remain ignored; only .env.example excepted.
• Scoped/staged diff check — passed; runtime source, schemas, contracts, dependency manifests/locks, CI and AGENTS.md unchanged.
• No local install, database setup, full app/Foundry test rerun or browser QA: docs/sample-only scope. Exact-head CI app and contracts passed: https://github.com/jh1nresh/agentshack/actions/runs/34253701528 (PR release-readiness is skipped by design).
• Independent read-only review PASS in a separate Codex task from the implementation task, for head b789248509227721296b8d4264e6c711a69a8b96 against base fb48ad842b0e4c7be8a03cd347d9d8eecdaf8bd3. All 13 changed paths inspected; 11 Markdown files and 89 local links/anchors rechecked, along with npm scripts, PostgreSQL/Privy configuration, archive preservation, pinned Foundry revisions and env ignore rules. No blocking findings or source edits. Review performed by the new task controller; no child-agent consensus claimed.

Delivery

Merged as 7871ce45d1ce67c25bb0c86d8803f0bebb4c4bad under the user's explicit authorization on 2026-09-09. Remote main and merge-tree equality with the reviewed head verified. Deployment is outside this request.

Post-merge CI: https://github.com/jh1nresh/agentshack/actions/runs/34370103208 . Lint, typecheck, tests, build and contracts passed, but audit:runtime failed and release-readiness was skipped. Four newly published advisories exceed the existing baseline: GHSA-2883-xcg3-v3hh (js-yaml), GHSA-p293-qw3h-jr36 and GHSA-2xp9-vwfh-vxw4 (Next.js), GHSA-rgj7-g3m4-5g8c (sharp). GitHub advisory publication timestamps are after the successful PR CI run. Dependency manifests, lockfiles and audit policy are unchanged by this docs PR. This is a dependency-security follow-up blocker; no claim of full main CI PASS or production exploitability. No audit baseline relaxation or dependency changes performed. CI readiness does not prove public deployment, mainnet readiness, completed funded hires or competition acceptance. Historical docs retain dated claims under explicit archive banners.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-09T15:26:23.708166Z	b789248	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.