# NEO App agent reference

This file is for AI agents and machine ingestion. The browser documentation is the concise, user-facing guide. Do not copy this entire file into a human article.

Production dashboard: https://portal.app.neoapp.id
Documentation version: 12.0.1

## Human-readable documentation

- Introduction: /#/introduction
- Account & token: /#/account-setup
- Connect an AI agent: /#/agent-cli-setup
- Deploy with an AI agent: /#/quickstart
- CLI quickstart: /#/cli-quickstart
- Projects and environments: /#/projects-environments
- Deploy from source or template: /#/repository-deployments
- Deploy a full-stack app: /#/full-stack-deployment
- Service types: /#/service-types
- Scheduled jobs: /#/scheduled-jobs
- PostgreSQL and MySQL: /#/databases
- Managed Redis: /#/redis
- Message queues: /#/queues
- Object storage: /#/object-storage
- Variables, secrets, and bindings: /#/variables-bindings
- Deployments and operations: /#/deployments-operations
- Logs and metrics: /#/logs-metrics
- Custom domains and TLS: /#/custom-domains
- Teams, roles, and approvals: /#/teams-approvals
- Tokens and agent sessions: /#/tokens-sessions
- Cost and safety: /#/cost-safety
- Usage and billing: /#/usage-billing
- MCP reference: /#/mcp-agent-guide
- CLI reference: /#/cli-reference
- Full-stack with an AI agent: /#/full-stack-agents
- Glossary: /#/glossary
- Troubleshooting: /#/troubleshooting

## Approved operating flow

MCP means Model Context Protocol. It is the standard connection an AI coding agent uses to call NEO App tools. Planning is zero-write; a human must approve the exact server-authored plan before apply.

Present task interfaces in this order: MCP, Portal, CLI. MCP is the recommended operating path. Use the Portal for the one-time account, project, and token setup and for visual administration; use the CLI for terminal-native control, scripts, and CI.

Human onboarding is intentionally split from technical reference:

- `/#/agent-cli-setup` is the short agent connection guide. It offers a prompt-first path using `https://portal.app.neoapp.id/prompt.md` and a manual `agent setup` path.
- `/#/quickstart` is the first agent-led deployment walkthrough.
- `/#/cli-quickstart` is the first direct terminal deployment walkthrough.
- `/#/mcp-agent-guide` and `/#/cli-reference` contain the detailed contracts needed by advanced users and agents.

Use this order for every billable or externally visible change, regardless of Portal, MCP, or CLI:

1. Scope: confirm actor, organization, project, and environment. Production is the default; Staging or another custom environment must be selected intentionally.
2. Inspect: read source or current resource state; collect missing configuration without mutation.
3. Plan: request a zero-write plan containing IDs, resource graph, provisioning order, public exposure, hourly IDR estimate, assumptions, cleanup, and expiry.
4. Approve: present the exact immutable plan and stop for human approval. Never approve on the user's behalf.
5. Provision: apply the approved plan once and retain its operation ID.
6. Verify: wait for terminal readiness, run a functional test, inspect usage, and report unresolved work.

For a full stack, phase 5 always uses this dependency order:

1. Foundations: database, Redis, queue, and object storage.
2. Connections: typed bindings and write-only secrets.
3. Applications: web services, workers, and static sites.
4. Edge and automation: custom domains, TLS, and scheduled jobs.

Cleanup uses the reverse order. A timeout is not permission to submit a second apply; resume the same operation ID.

## Custom environments

- Production remains the default. Create a custom environment only for an intentional isolated target such as QA, review, or training.
- Portal: open Project settings → Environments → Add environment; provide a clear display name and stable lowercase slug, review scope and billing, create it, then verify the environment badge.
- MCP: ask the agent to confirm identity and project, inspect capabilities, preview the custom-environment scope without mutation, and stop for approval before creation. It must not copy or deploy resources as part of environment creation.
- CLI: create with `neo-app environment create --project <project-id> --name "QA" --slug qa --json`, verify with `neo-app environment list --project <project-id> --json`, then select it with `neo-app link <project-id> --environment qa`.
- Services created or promoted into a custom environment are separate hourly-billed resources. Stopping compute does not delete retained storage charges.

## MCP behavior

- Discover the server contract first, then establish identity and scope.
- Prefer read-only inspection and planning before mutation.
- Use server-authored plans and exact plan hashes or confirmation tokens where required.
- Generated credentials are write-only. Bind them to named consumers; never reveal them in prompts, output, logs, URLs, screenshots, or ordinary variables.
- Wait for provider readiness before binding. Redeploy a consumer after adding or changing a binding.
- Submission, build completion, or URL creation is not success. Run the resource-specific functional verification.
- Use explicit IDs from tool results. Do not infer resources from display names when an ID is available.

Typical full-stack sequence:

1. `neo_get_capabilities`
2. `neo_whoami`
3. `neo_scan_repo`
4. `neo_plan_stack`
5. Human reviews and approves the exact plan
6. `neo_apply_stack`
7. `neo_wait_operation`
8. Resource verification and endpoint checks
9. `neo_reconcile_usage` or resource usage inspection

For a local folder, call `neo_deploy_folder` with `dryRun: true`, review its cost and specification, then repeat once with the returned confirmation token. For a template, list templates before selecting and deploying one.

## Scheduled jobs

- Treat a scheduled job as a scheduled HTTP request or application command, not as a repository service.
- For `http_endpoint`, resolve either a healthy NEO App Web Service plus path or a complete approved HTTPS URL before planning.
- Collect schedule type and value, timezone when applicable, method, repeated query parameters, headers, write-only secret references, optional body and content type, expected status, timeout, retry/backoff, concurrency policy, and a verification endpoint or observable effect.
- Supported HTTP methods are GET, POST, PUT, PATCH, DELETE, and HEAD. Never add a body to GET or HEAD unless the platform contract explicitly changes.
- Use `Forbid` when overlapping execution is unsafe; `Allow` permits overlap and `Replace` supersedes an active run.
- The Portal, MCP, and CLI must show the same resolved target and redacted request summary in the zero-write plan. Secrets must never appear in prompts, URLs, logs, screenshots, or output.
- After approval and creation, run once manually, inspect run history, response status, duration, and the functional result. Scheduler submission alone is not success.

## Prompt pattern

A safe user request contains the action and desired outcome, source or exact resource ID, project and environment, capacity constraints, intended consumers, public exposure, a requirement to show hourly cost before mutation, an explicit approval pause, and required functional verification.

```text
Deploy the source in this directory to my NEO App Production environment.
Confirm identity and scope, inspect the source, and show detected services,
dependencies, public exposure, provisioning order, and hourly IDR cost.
Do not apply anything until I approve the exact server-authored plan.
After approval, provision in dependency order, wait for readiness,
run functional verification, and summarize usage and remaining actions.
```

## Billing rules

- Every service type, including Object Storage, accrues hourly from its billable effective time.
- Promoting from Staging or another custom environment creates separately billed Production resources. The source environment continues billing until its compute is stopped or its resources are deleted; retained storage continues billing until deletion.
- Stopping or scaling compute to zero stops future compute-hour accrual at the effective timestamp.
- Persistent storage, retained database data, backups, public endpoints, and other non-compute resources continue accruing until resized or deleted.
- Deletion stops future accrual only after it becomes effective. Accrued usage remains payable.
- Always show hourly cost, monthly estimate assumptions, variable meters, and cleanup impact before approval.

## Session and token safety

- Terminating a session disconnects one selected live connection; the token may remain valid.
- Revoking a token invalidates that credential and every session using it.
- During an incident, terminate the untrusted session and revoke its token, then issue a newly scoped credential.
- Never request that a user paste a token into a prompt.