Agent install runbook

This page is written for the AI coding agent. If a user says “install Axint,” “read the docs and install Axint,” or “make sure Axint is working,” follow this runbook before editing Apple-native code.

Server started is not enough

“MCP server started” only proves the tool process launched. It does not prove Axint was actually used. The first-use proof is axint.activate through MCP, or axint activate --format json through the CLI. Do not claim the install is working until activation returns status: "ok" and signal: "axint_activated".

Copyable instruction

When a human wants to give this to an agent, use this short instruction:

Read https://docs.axint.ai/mcp/agent-runbook/ and install axint in this repo. Follow the runbook exactly: prove activation before editing Apple-native code, then tell me the version, activation result, and next Axint action.

Success criteria

An Axint install is complete only when you can report all of these:

• The running Axint version.
• The project directory you installed or initialized.
• The MCP connection status, if this host supports MCP.
• The activation result: status: "ok" and signal: "axint_activated".
• The current session token or workflow-check status.
• The next Axint action you will use before editing Apple-native code.

The runbook

1. Identify the repo and host.

   Run the cheap checks first. Do not edit source files yet.

   pwd
   node --version
   npm --version

   Axint requires Node.js 22 or newer. If Node is too old, stop and tell the user exactly what has to be upgraded.

2. Install the current Axint package.

   Prefer a project-local install when the repo has package.json; otherwise use npx for the first proof pass.

   Project local

   npm install --save-dev @axint/compiler
   npx axint --version

   No package.json yet

   npx -y -p @axint/compiler axint --version

   Global fallback

   npm install -g @axint/compiler
   axint --version

3. Write the project agent files.

   This gives Codex, Claude Code, Cursor, Xcode workflows, and future agents the same local Axint context.

   npx -y -p @axint/compiler axint project init --dir . --agent all --mode local
   npx -y -p @axint/compiler axint agent install --dir . --agent all --privacy local_only

   If the repo already has Axint-owned project files and the user did not ask for a rewrite, do not force overwrite them. Read the existing files and continue.

4. Connect or reload MCP.

   If the host supports MCP, reload only the Axint MCP server/tool process after install. Keep the same chat thread when the host allows it.

   Local stdio MCP config:

   {
     "mcpServers": {
       "axint": {
         "command": "npx",
         "args": ["-y", "-p", "@axint/compiler", "axint-mcp"]
       }
     }
   }

5. Prove Axint is active.

   MCP preferred

   Call these tools:

   axint.status
   axint.activate

   Report the running MCP version and the activation result.

   CLI fallback

   axint activate --format json
   npx -y -p @axint/compiler axint status --format json
   npx -y -p @axint/compiler axint activate --format json

   Activation must return status: "ok" and signal: "axint_activated". If axint.activate or axint activate is missing, the package or connected MCP process is stale. Run axint upgrade --apply, reload only the Axint MCP server/tool process, then repeat this step.

6. Start an Axint session.

   MCP preferred

   Call axint.session.start for the project and keep the returned sessionToken visible in the thread.

   CLI fallback

   npx -y -p @axint/compiler axint session start --dir . --agent all --format json

   Read the generated context files before making Apple-native changes:

   • .axint/AXINT_REHYDRATE.md
   • .axint/AXINT_MEMORY.md
   • .axint/AXINT_DOCS_CONTEXT.md
   • AGENTS.md
   • CLAUDE.md
   • .axint/project.json

7. Run the context-recovery workflow check.

   MCP preferred

   Call axint.workflow.check with:

   {
     "stage": "context-recovery",
     "sessionToken": "<token from axint.session.start>",
     "readRehydrationContext": true,
     "readAgentInstructions": true,
     "readDocsContext": true,
     "ranStatus": true
   }

   CLI fallback

   npx -y -p @axint/compiler axint workflow check \
     --dir . \
     --agent all \
     --stage context-recovery \
     --session-token <token from axint session start> \
     --read-rehydration-context \
     --read-agent-instructions \
     --read-docs-context \
     --ran-status

   If the check is not ready, follow the returned next action before editing.

8. Only now start the Apple-native work.

   Use Axint tools as the loop, not as a one-time install checkbox:

   • Use axint.suggest or axint.feature before inventing new Apple features.
   • Use axint.compile or axint.validate for generated definitions.
   • Use axint.swift.validate for existing Swift.
   • Use axint.cloud.check when hosted compatibility feedback is useful.
   • Use axint.run for the full proof loop when a Mac/Xcode build is needed.
   • Use axint.workflow.check again at planning, before-write, pre-build, and pre-commit checkpoints.

What to report back

After installation, reply with a compact proof report:

Axint install proof:
- Project: <absolute repo path>
- Version: <running Axint version>
- MCP: <connected / not available / reloaded>
- Activation: status=<ok>, signal=<axint_activated>
- Session: <session token or workflow-check status>
- Next Axint action: <tool or CLI command>

Do not say “Axint is installed” if you only started the MCP server. Say what is missing and keep going until activation proof exists.

Common failure paths

axint.activate is not visible in MCP

The MCP process is stale. Upgrade Axint, reload only the Axint MCP server/tool process, call axint.status, then call axint.activate again. If local project files still name an older expected version after the upgrade, call axint.project.syncVersion before continuing.

npx -y -p @axint/compiler axint upgrade --apply

axint activate is an unknown CLI command

You are running an old Axint package. Install the latest package and retry:

npm install --save-dev @axint/compiler@latest
npx axint activate --format json

Node is older than 22

Stop before editing code. Tell the user Axint needs Node.js 22 or newer.

The host cannot use MCP

Use CLI fallbacks for status, activate, session start, and workflow check. Do not skip the proof loop just because MCP is unavailable.

No Mac or Xcode is available

You can still run Axint validation, Cloud Check, project indexing, and workflow checks. Full xcodebuild and runtime proof require a Mac with Xcode.