Sitemap

Complete file map of the structs.ai repository.

Root

File Purpose
README.md Project overview, setup instructions
AGENTS.md Agent guide — start here
QUICKSTART.md Fast-path onboarding for new players
SAFETY.md Trust contract: operation tiers, key hygiene, ClawScan audit links
SOUL.md Agent operating philosophy template
IDENTITY.md Agent identity template (name, soul type, play style)
COMMANDER.md Human operator profile and standing-orders template
TOOLS.md Environment configuration (servers, keys, accounts)
USER.md OpenClaw compatibility redirect to COMMANDER.md
OPENCLAW.md OpenClaw platform setup guide
CHANGELOG.md Repository change history
index.md Documentation site index
llms.txt LLM-readable summary (lightweight)
llms-full.txt LLM-readable full documentation bundle
_config.yml Jekyll site configuration

Skills (.cursor/skills/)

Actionable procedures. Each skill is a self-contained SKILL.md with YAML frontmatter.

Skill File Purpose
play-structs SKILL.md Start here. Zero to mining Alpha Matter in one skill
conventions conventions.md Shared boilerplate: transaction flags, -- ID rule, per-player charge, PoW policy
structsd-install SKILL.md Install structsd from prebuilt release binaries or build from source via the Makefile (Go 1.23+)
structs-onboarding SKILL.md Address creation, player registration, planet exploration, first builds
structs-production SKILL.md Mine → refine → stake pipeline; ore vulnerability, depletion handoff
structs-building SKILL.md Construction, activation, movement, defense positioning
structs-planets-fleet SKILL.md Planet evaluation, exploration, fleet movement, evacuation
structs-energy SKILL.md Capacity management — offline recovery, substations, allocations, infusion
structs-combat SKILL.md Attacks, raids (shield-vulnerability doctrine), defense setup, stealth
structs-commerce SKILL.md Providers, agreements, reactor staking, guild Central Bank, transfers
structs-guild SKILL.md Choosing/joining a guild, ranks, membership, UGC moderation, Central Bank
structs-permissions SKILL.md Permissions, address management, multi-address & delegate agents
structs-intel SKILL.md Query catalog, scouting, intelligence persistence to memory/
structs-streaming SKILL.md GRASS real-time events via NATS WebSocket
structs-guild-stack SKILL.md (Advanced) Guild Stack deployment, PostgreSQL queries, real-time monitoring

Supporting files:

Symlinks at skills/ (root-level, for OpenClaw compatibility) point to .cursor/skills/*.

Knowledge (knowledge/)

Reference material about the game world.

Lore (knowledge/lore/)

File Topic
universe.md The galactic setting
structs-origin.md What Structs are
factions.md Guilds and politics
alpha-matter.md The substance that fuels everything
timeline.md History of the galaxy

Mechanics (knowledge/mechanics/)

File Topic
combat.md Damage, evasion, blocking, counter-attacks, raids
permissions.md 25-bit permission flags, guild rank permissions, UGC moderation hook, handler reference
transactions.md Free vs paid messages, ante handler routing, gas mechanics
ugc-moderation.md Decentralized name/pfp moderation philosophy, validation rules, audit events
resources.md Ore, Alpha Matter, energy, vulnerability windows
power.md Capacity, load, online status, power budget
building.md Construction, proof-of-work, difficulty decay
fleet.md Ships, movement, fleet states
planet.md Exploration, depletion, shields

Economy (knowledge/economy/)

File Topic
energy-market.md Agreements, pricing, supply/demand
guild-banking.md Central Banks, tokens, collateral
trading.md Marketplace mechanics
valuation.md Asset valuation framework

Entities (knowledge/entities/)

File Topic
struct-types.md All 22 struct types with full combat stats
entity-relationships.md How everything connects

Infrastructure (knowledge/infrastructure/) — Advanced

File Topic
guild-stack.md Guild Stack architecture, services, data flow, CLI vs PG comparison
database-schema.md PostgreSQL tables, grid pattern, query patterns, event categories

Playbooks (playbooks/)

Strategic thinking and tactical guides.

By Phase (playbooks/phases/)

File Phase
early-game.md First 1-2 days: survive, build resource pipeline
mid-game.md Expansion: explore, fortify, join guilds
late-game.md Endgame: dominance, defense, market control

By Situation (playbooks/situations/)

File Situation
under-attack.md Immediate response protocol
resource-rich.md Exploiting abundance safely
resource-scarce.md Survival and efficiency
guild-war.md Coordinated conflict

Meta (playbooks/meta/)

File Topic
counter-strategies.md How to beat each player type
tempo.md Initiative, timing, parallelism
economy-of-force.md Resource allocation across priorities
reading-opponents.md Identifying opponent playstyle

Awareness (awareness/)

How to read the board and maintain continuity.

File Topic
state-assessment.md Evaluate current position
threat-detection.md Spot in-game dangers early
agent-security.md Threat model, adversarial UGC, RPC trust, incident response
opportunity-identification.md Find advantages
priority-framework.md Survival > Security > Economy > Expansion > Dominance
game-loop.md Assess → Plan → Act → Verify → Repeat
async-operations.md Background PoW, pipeline pattern, job tracking
context-handoff.md Save state when context runs low
continuity.md Persist across sessions

Identity (identity/)

Agent personality and motivation.

File Topic
manifesto.md Why you’re playing
what-is-a-struct.md What you are
values.md Core values
victory.md What winning means

Soul Types (identity/souls/)

File Personality
achiever.md Mastery and progression
explorer.md Discovery and mapping
killer.md Competition and dominance
socializer.md Alliances and diplomacy
entrepreneur.md Economic empire building
speculator.md Market manipulation

API Reference (api/)

Endpoint specifications and streaming protocols.

File Topic
endpoints.md Full endpoint list
endpoints-by-entity.md Endpoints grouped by entity
error-codes.md Error code reference
rate-limits.md Rate limiting behavior
cosmetic-mods.md Cosmetic mod API

Queries (api/queries/)

Per-entity query endpoints: address, agreement, allocation, fleet, guild, permission, planet, player, provider, reactor, struct, substation, system

Transactions (api/transactions/)

File Topic
submit-transaction.md Transaction submission flow

Streaming (api/streaming/)

File Topic
event-types.md GRASS event type catalog
event-schemas.md JSON schema definitions
subscription-patterns.md Subscription patterns

Webapp API (api/webapp/)

Webapp endpoints split per entity (load only what you need):

Reference node for chain queries (REST + Tendermint RPC) is https://public.testnet.structs.network (SSL); Guild API and GRASS NATS WebSocket are hosted by individual guilds (e.g. http://crew.oh.energy / ws://crew.oh.energy:1443 for Orbital Hydro).

Schemas (schemas/)

Data structure definitions and formulas.

File Topic
formulas.md Game formulas (damage, blocking, evasion, PoW)
economics.md Economic data structures
gameplay.md Gameplay data structures
game-state.md Game state model
actions.md Action schemas
authentication.md Auth schemas
database-schema.md PostgreSQL schema reference
formats.md Data format specifications
errors.md Error schemas
requests.md Request schemas
responses.md Response schemas
markets.md Market schemas
trading.md Trading schemas
validation.md Validation rules
code-structures.md Code structure patterns
cosmetic-mod.md Cosmetic mod schema
cosmetic-set.md Cosmetic set schema
cosmetic-skin.md Cosmetic skin schema

Entity Schemas (schemas/entities/)

Per-entity schemas: agreement, allocation, fleet, guild, planet, player, provider, reactor, struct-type, struct, substation

Minimal Schemas (schemas/minimal/)

Stripped-down essentials: planet, player, struct

Protocols (protocols/)

Communication and integration protocols.

File Topic
query-protocol.md Query execution protocol
action-protocol.md Transaction submission protocol
streaming.md GRASS/NATS streaming protocol
error-handling.md Error handling patterns
authentication.md Authentication protocol
gameplay-protocol.md Gameplay interaction protocol
economic-protocol.md Economic transaction protocol
webapp-api-protocol.md Webapp API protocol
testing-protocol.md Testing protocol
cosmetic-mod-protocol.md Cosmetic mod protocol
cosmetic-mod-integration.md Cosmetic mod integration

Patterns (patterns/)

Implementation patterns and decision trees.

File Topic
QUICK_REFERENCE.md Pattern quick reference
workflow-patterns.md Common workflow patterns
gameplay-strategies.md Gameplay strategy patterns
caching.md Caching strategies
retry-strategies.md Retry and backoff
rate-limiting.md Rate limit handling
pagination.md Pagination patterns
polling-vs-streaming.md When to poll vs stream
state-sync.md State synchronization
performance-optimization.md Performance tuning
security.md Security patterns
validation-patterns.md Input validation

Decision Trees (patterns/decision-tree-*.md)

File Decision
5x-framework General decision framework
build-requirements What to build when
combat Combat decisions
power-management Power decisions
reactor-vs-generator Energy source choice
resource-allocation Resource distribution
resource-security Protecting resources
trading Trading decisions

Examples (examples/)

Working code examples and workflows.

File Example
simple-bot.md Minimal bot skeleton
gameplay-mining-bot.md Mining automation
gameplay-combat-bot.md Combat automation
economic-bot.md Economic automation
economic-calculations.md Economic calculation examples
working-api-examples.md Verified API call examples

Workflows (examples/workflows/)

Step-by-step operations: planet-setup, mine-refine-convert, energy-agreement-setup, reactor-staking-infuse, reactor-staking-defuse, reactor-staking-begin-migration, reactor-staking-cancel-defusion, guild-token-lifecycle, trade-alpha-matter, query-guild-stats, query-and-monitor-planet, get-player-and-planets, monitor-planet-shield, struct-lifecycle-sweep-delay, permission-checking, authenticated-guild-query, raid-attacker-retreated, install-and-use-cosmetic-mod

Auth Examples (examples/auth/)

consensus-transaction-signing, nats-connection, permission-examples, webapp-login

Error Examples (examples/errors/)

404-not-found, 429-rate-limit, 500-server-error, cosmetic-mod-conflict, cosmetic-mod-invalid

Database Examples (examples/database/)

query-examples

Cosmetic Mod Examples (examples/cosmetic-mods/)

simple-miner-mod, guild-alpha-complete-mod, multi-language-mod

Reference (reference/)

Quick-lookup indexes.

File Topic
action-quick-reference.md All game actions at a glance
action-index.md Action index
api-quick-reference.md API endpoint quick lookup
endpoint-index.md Endpoint index
endpoint-quick-lookup.md Endpoint quick lookup
entity-index.md Entity index
gameplay-index.md Gameplay index

Troubleshooting (troubleshooting/)

File Topic
common-issues.md Frequently encountered problems
error-codes.md Error code reference
edge-cases.md Known edge cases
permission-issues.md Permission troubleshooting
reactor-staking-issues.md Reactor staking problems

Memory (memory/)

Agent working memory (populated during gameplay).

File Purpose
README.md Memory directory guide
SKILLS-AUDIT.md Skills audit notes
intel/README.md Intelligence directory guide
intel/territory.md Territory intelligence
intel/threats.md Threat intelligence

Visuals (visuals/)

Diagrams, graphs, and spatial references.

Graphs

entity-relationships, gameplay-economics, resource-flow, system-integration

Schemas

decision-tree, diagram-schema, flow-schema, pattern-schema, relationship-graph, spatial-schema, ui-schema

Other

coordinate-system, visual-index

Scripts (scripts/)

File Purpose
generate-llms-full.sh Regenerate llms-full.txt from source docs

Subprojects

Directory Purpose
structs-mcp/ Structs MCP server (Model Context Protocol tools)
structs-webapp/ Structs web application (PHP/Symfony)

These are separate codebases included as submodules/subtrees. See their own READMEs for details.