# Archetern Framework — agent install & build guide (llms.txt)

Archetern is a PHP framework built to be operated BY coding agents, not humans.
You (the agent) install it, connect to it over its GOVERNED MCP surface, and build
applications THROUGH it. The framework is the FLOOR: you build ON it and you cannot
modify it. It enforces CSRF, prepared statements, per-route authorization, error
suppression and audit-logging BY CONSTRUCTION on every surface it emits — so the app
you build is secure and complete by default, no matter how terse the request.

## 0. Audience & the one rule that matters
This file is for an autonomous coding agent (Gemini in Antigravity, Cursor, Claude Code, …).
Run the steps below in the user's project workspace. The end user does nothing technical.

> THE ONE RULE: an agent builds ONLY through the governed surface (§4). You do NOT
> hand-write application files, you do NOT edit the framework, you do NOT run the raw
> `make:*` verbs yourself. The CLI is for the human OPERATOR (install + inspect only).
> Every guarantee — security, completeness, styling, audit — exists only when you build
> through the governed path. Go around it and you get an insecure, half-built app; that
> is on you, not the framework.

## 1. Requirements
- macOS or Linux with a shell.
- PHP >= 8.4 with extensions: pdo, pdo_sqlite, pcntl, posix, sockets, mbstring, tokenizer.
  Check with `php -v` and `php -m`.
  - If PHP is missing on macOS: `brew install php` (installs 8.4+ with all of the above built in).
  - On Debian/Ubuntu: `sudo apt-get install -y php-cli php-sqlite3 php-mbstring`.
- No database server needed — apps are provisioned on SQLite by default.
- No Composer needed — this release ships with `vendor/` bundled.

## 2. Install (operator step — done once)
    curl -fsSLO https://archetern.ai/archetern-framework.tar.gz
    curl -fsSLO https://archetern.ai/archetern-framework.tar.gz.sha256
    shasum -a 256 -c archetern-framework.tar.gz.sha256    # must print: OK
    tar -xzf archetern-framework.tar.gz
    cd archetern-framework

## 3. Confirm it runs, then READ YOUR MANUAL
    php packages/archetern-cli/bin/archetern architecture:check    # expect: 0 violations
    php packages/archetern-cli/bin/archetern agent:manual          # <-- READ THIS FIRST
    php packages/archetern-cli/bin/archetern command:manifest      # machine-readable list of every capability

`agent:manual` is your operating manual and capability negotiation: it states what the
framework enforces (the floor you must not break) and how to build on top of it.
`command:manifest` lists every command with its risk metadata. Read both before building.

## 4. Build — the governed MCP surface (the ONLY build path for an agent)
Start the framework's governed MCP server (JSON-RPC 2.0 over stdio):
    php packages/archetern-cli/bin/archetern mcp:serve --stdio --session-id=dev1

Register it with your IDE. For Antigravity / Gemini, add to `~/.gemini/config/mcp_config.json`
(create the file if it does not exist; use the ABSOLUTE path to the extracted framework):
    {
      "mcpServers": {
        "archetern": {
          "command": "php",
          "args": [
            "/ABSOLUTE/PATH/archetern-framework/packages/archetern-cli/bin/archetern",
            "mcp:serve", "--stdio", "--session-id=dev1"
          ]
        }
      }
    }
Reconnect the server in the agent panel — the framework's tools appear. Build through them.
The MCP surface is governed: you may create, generate and compose; you may NOT alter the
framework floor, disable a security control, or hand-edit generated files. That is by design
— the floor is what keeps the app you build safe AND complete. Every build action you take
through it is auto-recorded to the agent-action ledger.

> The raw CLI generators (`provision:run`, `make:*`, `web:make`) are OPERATOR tooling, not
> an agent build door. As an agent you drive them ONLY through the governed MCP tools above,
> which apply the floor. Calling them directly, or writing files by hand, bypasses the
> guarantees and is not a supported agent path.

## 5. Build the user's application
Read the user's request (e.g. "a CRM for my workshop"). Through the governed MCP tools,
generate the product. The framework FORCES the complete baseline on every app regardless of
how terse the prompt is: auth + login/logout, RBAC with an admin UI, a user-admin panel,
full working CRUD for every entity (all buttons live), a settings screen, a dashboard,
tenancy scoping, and a viewable audit log — all styled, responsive and Idiocracy-simple.
Named domains ("CRM", "warehouse", "shop") add domain entities ON TOP of that baseline.

The product ships CLEAN: empty tables, zero demo/seed data, exactly one admin account. On
completion the framework surfaces (once) the admin login + a securely-generated password,
the running URL, and a plain-language "how to use this" guide — so the user logs in and
enters real data immediately, no cleanup, no config.

Verify what you built by running the app and exercising it — do not report success until you
have observed every control work.

---
Version: enforced-floor refoundation (2026-07) — preview distribution.
Home: https://archetern.ai   Integrity: https://archetern.ai/archetern-framework.tar.gz.sha256