# 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: 11.3.0

## Human-readable documentation

- Introduction: /#/introduction
- Quickstart: /#/quickstart
- Account and token: /#/account-setup
- 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
- Connect an AI agent: /#/agent-cli-setup
- MCP guide: /#/mcp-agent-guide
- CLI guide: /#/cli-reference
- Full-stack with an AI agent: /#/full-stack-agents
- Troubleshooting: /#/troubleshooting

## Approved operating flow

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

1. Scope: confirm actor, organization, project, and explicit staging or production environment.
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.

## 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.

## 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 Staging project.
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.
- 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.