AGENTS.md

Trishool SN23 Docs Repo

Start Here

• Read docs/plans/2026-03-19-trishool-sn23-docs-site.md first.
• Use this file as the operating guide for repo intent, constraints, and content boundaries.

Project Purpose

• Build a miner-first public documentation site for Trishool Subnet 23 (SN23).
• The public site should explain the protocol clearly enough for miners to understand the challenge model, submission rules, validation flow, scoring, and rewards.
• The site should include enough surrounding Trishool context to explain why SN23 exists, but miner usability takes priority over broad product storytelling.

Audience Priority

• Primary audience: miners.
• Secondary audience: readers who need concise project context to understand the miner guide.
• Do not let investor-style or product-marketing material dominate the documentation experience.

Canonical Sources

• miner_context.md
  • Primary public-facing source for stable protocol and miner guide content.
• vision.pdf
  • Secondary source for public framing and project context.
• PHASE 2 - MIner Schema.pdf
  • Secondary source for submission schema examples and surface-area examples.
• design_contex.md
  • Internal-only reference.
  • Use it to understand intent, unresolved mechanics, and questions to raise.
  • Do not publish its unresolved design details directly.

Public vs Internal Boundary

• Public docs must be derived from reviewed, stable facts.
• Internal design notes are reference-only unless a human explicitly promotes specific details into approved public copy.
• Keep these out of public docs unless resolved and approved:
  • similarity implementation details
  • judge prompt design
  • judge-gaming mechanics
  • unresolved stateful attack rules
  • unresolved no-success edge cases
  • internal failure attribution mechanics

Core Constraints

• Unresolved protocol mechanics require a review gate before publication.
• Git history is the only required versioning model in v1.
• The docs workflow should stay static and Markdown-first.
• GitHub is the source of truth for content updates.
• Cloudflare should auto-publish from GitHub after merge.

Preferred Stack

• Astro Starlight
  • Best fit for a static Markdown docs site with a polished GitBook-like UX.
• Pagefind
  • Preferred local/static search solution.
• Cloudflare Pages
  • Preferred hosting and preview/production deployment path.

Expected Initial Site Sections

• Overview
• Challenge lifecycle
• Objectives and categories
• Submission rules
• Schemas / surface areas
• Similarity
• Validation pipeline
• Scoring
• Rewards and emissions
• Leaderboard and manual review
• FAQ / glossary

Working Rules For Agents

• Do not invent protocol details.
• Elevate ambiguity into a gap register instead of guessing.
• Standardize terminology before expanding content.
• Prefer concise canonical docs over dumping raw note text into pages.
• Keep marketing copy subordinate to miner usability.
• Keep the public site miner-first even when using vision.pdf for framing.
• If a source conflicts with another source, treat it as unresolved until reviewed.

Terminology Defaults

• Treat constitutional safety and LLM security as paired terms.
• Treat agent boundary integrity and agentic security as paired terms.
• Treat submission period and training period as the canonical lifecycle phases.
• Treat submission as the 12-entry miner payload and entry as one attack item within it.

Definition Of Done For V1

• A static docs site builds locally.
• Miner-critical rules are easy to find and hard to misread.
• Search works across the core miner terms.
• Cloudflare preview and production deploy paths are configured from GitHub.
• Public docs exclude unresolved internal mechanics.

Repo Handoff Contract

• AGENTS.md is the first-read file for future agents.
• docs/plans/2026-03-19-trishool-sn23-docs-site.md is the canonical execution plan.
• If implementation details are missing from this file, extend the plan document rather than relying on chat history.