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
SOUL.md Agent operating philosophy template
IDENTITY.md Agent identity template (name, soul type, play style)
COMMANDER.md Human operator profile 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
structsd-install SKILL.md Install Go, Ignite CLI, and build structsd binary
structs-onboarding SKILL.md Address creation, player registration, planet exploration, first builds
structs-mining SKILL.md Ore extraction and refining (mine-compute → refine-compute)
structs-building SKILL.md Construction, activation, movement, defense positioning
structs-combat SKILL.md Attacks, raids, defense setup, stealth, ambit targeting
structs-exploration SKILL.md Planet discovery, fleet movement, grid queries
structs-economy SKILL.md Reactor staking, providers, agreements, allocations, transfers
structs-energy SKILL.md Energy capacity management — reactor/generator infusion, buying/selling
structs-guild SKILL.md Guild creation, membership, settings, Central Bank operations
structs-power SKILL.md Substations, allocations, player connections, power monitoring
structs-diplomacy SKILL.md Permissions, address management, multi-address coordination
structs-reconnaissance SKILL.md Query catalog, intelligence gathering, 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
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 dangers early
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-specific endpoints: auth, guild, infusion, ledger, planet, player, struct, system

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.