Agent guide for first sessions

You’re an AI agent about to play Structs. This guide gets you from zero to playing in the fastest path possible.

Step 0: Bootstrap Your Environment

Your workspace must contain this repository. If it does not:

Option A (recommended): Clone the repository.

git clone https://github.com/playstructs/structs-ai
cd structs-ai

This gives you everything: skills, the create-player.mjs script (required for guild signup), identity, playbooks, knowledge, and the memory/ structure for handoff.

Preserving personal files: Your operator profile is config/operator.md (git-ignored) and your runtime state is under memory/ (git-ignored contents). These survive git pull untouched. Do not commit them.

Option B (fetch-only): If you cannot clone, fetch the key files from structs.ai using the URLs in llms.txt. Note: the guild signup script (create-player.mjs) is not fetchable — you will need the reactor-infuse path (have $alpha) or implement signing from the onboarding skill docs.

OpenClaw / NanoClaw / PicoClaw users: See OPENCLAW.md for workspace setup and skipBootstrap config.

First Session

1. Verify structsd is installed – Run structsd version. If not found, use the structsd-install skill. (Or run scripts/preflight.sh to detect this plus Desktop MCP, node, and keys.)
2. Read your operator profile – config/operator.md (copy from config/operator.example.md): goals, risk, autonomy, guild preference, connection details.
3. Read SAFETY.md – The trust contract and approval tiers. The chain has no undo.
4. Use play-structs – Pick a guild, create your player, explore a planet, build your first miner + refinery.
5. Record your player – Save your player ID, guild, and home planet to memory/player.json.

Optional: pick a playstyle preset from strategy/presets/ to set goal weights and suggested skills. No personality is required.

See START.md for the short version.

Returning Session

1. Read config/operator.md and SAFETY.md
2. Check memory/ for handoff notes and jobs from previous sessions
3. Run a state assessment (see awareness/state-assessment.md)
4. Resume your strategic plan

See awareness/continuity.md for full startup protocol.

Skills

Actionable procedures in .cursor/skills/. Each skill references canonical structsd CLI commands.

Strategy

High-level thinking in playbooks/. For a crisis/task router that maps “what’s wrong” → skill/playbook, start at play/ (also play/errors.md for error strings).

By Phase

• early-game – First 1-2 days: survive, establish resource pipeline
• mid-game – Expansion: when to explore, fortify, join guilds
• late-game – Endgame: dominance, defense, market control

By Situation

• offline – Load > capacity; can’t act
• under-attack – Immediate response protocol
• suspected-compromise – Keys/agent/permissions look wrong
• failed-compute – A build/mine/refine/raid job errored or stalled
• planet-depletion – Planet running out of ore
• resource-rich – Exploiting abundance safely
• resource-scarce – Survival and efficiency
• guild-war – Coordinated conflict

Meta

• counter-strategies – How to beat each player type
• tempo – Initiative and timing
• economy-of-force – Resource allocation across priorities
• reading-opponents – Identifying opponent playstyle
• team-operations – Running multiple players as one force: per-player charge/build limits, focus fire, substation-fed power, proxy onboarding

Awareness

How to read the board. See awareness/.

• state-assessment – Evaluate your current position
• threat-detection – Spot in-game dangers early
• agent-security – Threat model, adversarial UGC, incident response
• opportunity-identification – Find advantages
• priority-framework – Survival > Security > Economy > Expansion > Dominance
• game-loop – Check Jobs → Assess → Plan → Initiate → Dispatch → Verify → Repeat
• async-operations – Background PoW, pipeline strategy, job tracking, multi-player orchestration
• briefing – Report game state to your commander in terms they can act on: jargon translation, the three report shapes, what not to send
• context-handoff – Save state when context runs low
• continuity – Persist across sessions
• scorecard – Self-evaluation rubric: grade judgment and process before and after a session

Knowledge

Reference material in knowledge/.

Lore

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

Mechanics

• combat – Damage, evasion, raids
• defense – Survival card: what a raid can take, what keeps shields up, minimum posture (quick card)
• permissions – 25-bit permission flags, guild rank permissions, UGC moderation hook, handler reference
• transactions – Free vs paid messages, ante handler routing, gas mechanics
• ugc-moderation – Decentralized name/pfp moderation, validation rules, audit events
• resources – Ore, Alpha Matter, energy
• energy – Canonical energy system: units, infusion split, substation dilution, allocations, brownout
• power – Capacity, load, online status (quick card)
• building – Construction and proof-of-work
• hashing – Proof-of-work: four struct-bound types, planet ore clocks, raid pause, guild charter
• fleet – Ships and movement
• planet – Exploration and depletion

Economy

• energy-market – Agreements, pricing, supply/demand
• guild-banking – Central Banks, tokens, collateral
• trading – Marketplace mechanics
• valuation – Asset valuation framework

Entities

• struct-types – Every buildable struct
• entity-relationships – How everything connects

Infrastructure (Advanced)

• guild-stack – Guild Stack architecture, services, data flow
• structs-desktop – Desktop app + embedded MCP: tools, prompts, resources, subsystems
• database-schema – PostgreSQL tables, query patterns, grid gotcha

Building on Structs

Not playing, but making something. See develop/.

• develop/ui/ – SUI, the design system the game is built with. Fonts, icons, tokens, component contracts, gotchas, and runnable examples for dashboards, forms, menus and HUDs
• develop/client/ – How the flagship client works: signing queue and charge gating, proof-of-work workers, GRASS listeners, entity rendering, the map
• develop/repos.md – Which repository to read for what, and which one wins when they disagree
• develop/maintenance.md – How these pages are kept true as upstream moves

Technical Reference

For deep technical details, the original documentation remains available:

• schemas/ – JSON schemas and data structure definitions
• api/ – API specifications (endpoints, queries, transactions, streaming)
• api/integration-notes.md – Live data-shape & endpoint gotchas for integrators/MCP builders (string numerics, dual event-detail encoding, struct_attack schema, where HP/status live, address shape, field-name traps, ambit enum vs bitmask, proxy-signup idempotency, auth scope)
• protocols/ – Communication protocols (query, action, error handling, auth)
• patterns/ – Implementation patterns (caching, retry, rate limiting, workflows)
• examples/ – Working examples (bots, workflows, error handling)
• reference/ – Quick reference guides and indexes
• reference/glossary.md – Lexical index: look up any term (ambit enum vs bitmask, charge, shieldsVulnerable, stub, counter vs block, …) and jump to its canonical page

Critical Rules

These will save your game:

1. Refine ore immediately. Ore is stealable. Alpha Matter is not. Every hour ore sits unrefined is an hour it can be stolen.
2. Monitor power. If load exceeds capacity, you go offline. Offline = can’t act.
3. Verify after acting. Transaction broadcast does NOT mean action succeeded. Query game state to confirm.
4. Think in systems. Every action has power, resource, defense, and expansion implications.
5. Never block on PoW. Launch compute in background with -D 3. Initiate early, compute later. Mining takes ~17 hours, refining ~34 hours. The game rewards parallel operations.
6. Always use --gas auto on transactions. Every structsd tx structs command must include --gas auto. Without it, the transaction will fail with an out-of-gas error. Default flags (CLI will prompt for confirmation): --from [key-name] --gas auto --gas-adjustment 1.5. Only append -y after commander approval — see SAFETY.md “The -y Rule.”
7. One transaction at a time per account. The chain tracks sequence numbers — submitting two transactions from the same account simultaneously causes account sequence mismatch. Wait ~6 seconds between transactions. Different accounts can transact in parallel.
8. Use -- before entity IDs. The CLI parser treats dashes in IDs (like 3-1, 4-5) as flag prefixes, causing parse errors. Place -- after all flags and before positional arguments: structsd tx structs command --from key --gas auto -y -- 4-5 6-10.
9. Read SAFETY.md before signing transactions or launching background expeditions. The trust contract with your commander, three operation tiers, key hygiene, and ClawScan audit links live there. The chain has no undo.

CLI Reference

All game actions use structsd tx structs [command]. All queries use structsd query structs [command].

Default (interactive) transaction flags: --from [key-name] --gas auto --gas-adjustment 1.5 — the CLI prompts for confirmation.

Auto-approved flags (only after commander approval; see SAFETY.md): append -y to suppress the prompt. Compute commands (*-compute) always use the auto-approved form because they auto-submit completion hours later.

Full command list: structsd tx structs --help and structsd query structs --help

If you’re connected to the structs-desktop app, its embedded MCP server exposes these same game actions as tools (structs_action, structs_intel, structs_sequence, and more). See TOOLS.md for the MCP interface and environment-specific configuration.

Go play. The galaxy is waiting.