Your coding agent

Check the deployment prerequisite first#

Farther Shore is the gateway, billing, and entitlement plane in front of an HTTP service that the builder runs. Before creating a business, confirm the session has (a) somewhere to run a long-lived HTTP service on a public HTTPS URL, (b) the ability to set environment variables there for FS_RUNTIME_TOKEN, and (c) a way to read that service's logs. If any is missing, stop and ask the human — or provision it with OpenTofu when cloud credentials already exist and the human approves. Going live requires a bound production origin for every declared backend.

A coding agent operates Farther Shore through three sources, in this order:

1. the managed repository, including its AGENTS.md, for business-specific contract and application code;
2. the installed farthershore CLI for live platform operations;
3. this documentation for product behavior and edge cases.

Start every task with live context#

curl -fsSL https://docs.farthershore.com/llms.txt
farthershore auth whoami --format json
farthershore operations list --format json

llms.txt is the machine-readable index of the current documentation. Follow the exact page for the task instead of relying on a memorized command. The operation catalog is generated from the same registry that powers the CLI; it states whether an action is repository-authored, Git-triggered, available as a command, or intentionally belongs to another principal.

Authentication is deliberately simple#

farthershore login --headless
farthershore auth organization list --format json
farthershore auth organization use <id-or-slug>

Normal login creates a user-bound CLI session. It follows the approving user's live roles across every current and future organization and business; there are no permission, organization, or business choices during login. Selecting an organization changes command context, not authority.

Use a separately issued, organization-scoped MakerToken only when automation must be narrower than the user. Pipe it from a secret provider with farthershore login --token-stdin, or set FARTHERSHORE_TOKEN for one process. Never place a credential in argv or logs.

Create and enter the managed repository#

CREATE_ATTEMPT=$(node -e 'console.log(crypto.randomUUID())')
REPO_URL=$(farthershore business create quillby \
  --idempotency-key "$CREATE_ATTEMPT")
git clone "$REPO_URL"
cd quillby

Creation succeeds only after the managed GitHub repository exists. The command prints its URL as the handoff. The repository contains tooling and instructions, not a sample business. Read AGENTS.md, gather the product requirements, and author the filename-agnostic business/ program from scratch.

Use the correct change path#

Read Ownership boundaries before acting when the owner is ambiguous.

The build and apply loop#

farthershore build --format json
farthershore validate --format json
git add business/
git commit -m "define business behavior"
git push
farthershore apply-timeline list quillby --format json

The repository checks are named farthershore/build (Manifest IR build) and farthershore/apply (compile, accept, publish to edge); a customized portal also reports farthershore/frontend. farthershore/validate fires only on pull requests — after a plain branch push, waiting for it is waiting for a check that will never appear.

Stop on a failed local build. After a push, inspect the GitHub checks and Apply Timeline. A timeout does not prove a write failed. Follow the operation catalog's retry contract: only same_key_replay reuses a caller-persisted key, and every replay must be followed by its reconciliation read. See Retries and idempotency.

Choose the task guide#

• Quickstart — create the first business.
• Business program — author contract state.
• Backend setup — connect server logic and verified identity.
• Scaffold a backend — farthershore create api --node; never hand-write the verification middleware.
• Infrastructure with OpenTofu — one deployment and one runtime token per environment.
• Customer UI — build the customer-facing app.
• Environments — test safely before production.
• Releases — understand Git pushes, Releases, and rollbacks.
• CLI reference — operate current platform state.
• Response codes — branch on stable errors.

Agent operating rules#

• Run commands with --format json and branch on exit status, code, and op, never prose.
• Use --help for the installed command shape.
• Never claim business creation without the returned repository URL.
• Never report a push as live without reading its Apply Timeline and status.
• Treat production releases, economic changes, subscriber migrations, and destructive live operations as confirmation-gated.
• Preserve platform error evidence before retrying or escalating.
• Never put a key on a preview or a convergent desired-state write.
• Scaffold the backend with farthershore create api rather than hand-writing the raw-body capture or signature-verification middleware.
• Create the backend row before minting its runtime token, and pass --backend <backend-id> when an environment has several.
• Treat every push to an environment branch as destroying that environment's personas, subscriber keys, and customer rows; re-mint after each push.
• Never place a runtime token, subscriber API key, or persona session token in chat, argv, logs, or source control.