@biznetgio/neo-app 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @biznetgio/neo-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NEO App CLI — one-command agent onboarding, a local MCP server, and project ops for
+coding agents (Codex, Claude Code).
+
+## Quick start
+
+```bash
+npx -y @biznetgio/neo-app@latest agent setup
+# link a project:
+npx -y @biznetgio/neo-app@latest agent setup --project <project-id>
+```
+
+Or from a coding agent:
+
+```text
+Fetch https://portal.app.neoapp.id/prompt.md and follow it to set this repo up on NEO App.
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agent setup` | Authenticate, install the skill, register the MCP server, optionally link a project, health-check |
+| `agent doctor` | Diagnose CLI, API, auth, agent MCP wiring, skill, credential perms |
+| `agent uninstall` | Remove NEO App MCP entries, skill, (on confirm) credentials |
+| `config install-mcp [--agent codex\|claude-code]` | Register the `neo-app` MCP server with detected agents |
+| `login` | Authenticate with a NEO App API key (`kap_...`) |
+| `link <project-id>` | Link this repo to a project (writes `.neo-app.json`) |
+| `project list` | List projects in your organization (find ids to link) |
+| `status` / `whoami` | Show account, org, environment, linked project |
+| `mcp` | Run the local stdio MCP server (agents launch this) |
+
+All mutating commands are idempotent, back up config before editing, and never write a
+token into agent/MCP configuration.
+
+## Environments
+
+- **Production** (`https://portal.app.neoapp.id`) is the default.
+- **Staging** (`https://portal.neoapp.biznetgio.dev`) is selected by `--staging` or `NODE_ENV=development`.
+- `NEO_APP_URL` overrides the control-plane URL entirely (e.g. a local dev server).
+
+## Authentication
+
+API key (`kap_...`) for now. Create one in the portal (Settings → API tokens).
+
+- Interactive: `neo-app login` prompts (hidden) and stores the key at
+  `~/.config/neo-app/credentials.json` (mode `0600`), scoped per control-plane URL.
+- Headless/CI: `export NEO_APP_TOKEN=kap_...` — read from the environment, never persisted.
+
+The key is kept out of every agent/MCP config file; the MCP server reads it from the
+credential store (or `NEO_APP_TOKEN`) at runtime.
+
+## MCP tools
+
+`neo_whoami`, `neo_list_projects`, `neo_get_project`, `neo_list_services`,
+`neo_get_deployment`, `neo_deploy`, `neo_get_logs`, `neo_list_variables`,
+`neo_set_variable`, `neo_scale_service`, `neo_list_approvals`, `neo_get_approval`.
+
+Read-only tools are annotated `readOnlyHint`. Production/scaling/etc. operations may
+return a `pending_approval` result — that is the org approval policy working, not an error.
+
+## Develop
+
+```bash
+npm install
+npm test
+node bin/neo-app.js --help
+```

package/bin/neo-app.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/index.js';
+
+main().catch((e) => {
+  console.error(e?.message || e);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@biznetgio/neo-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "NEO App CLI — one-command agent onboarding, MCP server, and project ops for coding agents (Codex, Claude Code).",
+  "type": "module",
+  "bin": {
+    "neo-app": "bin/neo-app.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "prompt.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "keywords": [
+    "neo-app",
+    "biznetgio",
+    "mcp",
+    "agent",
+    "codex",
+    "claude-code",
+    "paas"
+  ],
+  "license": "UNLICENSED"
+}

package/prompt.md

@@ -0,0 +1,105 @@
+<!--
+NEO App setup prompt — served at https://portal.neoapp.biznetgio.dev/prompt.md (staging)
+and https://portal.app.neoapp.id/prompt.md (production).
+Contains NO credentials or user-specific secrets. Versioned; keep last-updated current.
+Keep this in sync with pkg/api/prompt.md (the copy the Go server embeds).
+-->
+# Set this repo up on NEO App
+
+**Version:** 0.4.0 · **Last updated:** 2026-10-12
+
+These are the official setup instructions from NEO App (Biznet Gio's managed-app
+platform). If you are an AI coding agent, complete the steps below yourself by running
+the commands directly — only stop where a step explicitly needs the human (handing over
+their API key, or choosing whether to create or link a project). Never put an API key
+into chat, repository files, the skill, or MCP configuration.
+
+## What NEO App runs
+
+Web services, background workers, scheduled jobs, static sites, managed databases
+(PostgreSQL/MySQL/…), queues (NATS), and object storage — on managed Kubernetes, served
+over HTTPS with automatic TLS. It is **not** for GPU training or for apps that need
+several containers running side by side at runtime (a single app container alongside
+managed databases is fine). If the repo has no server to put behind a URL (a library or
+a CLI tool), say so and stop.
+
+## 1. Install the CLI, skill, and MCP server
+
+One command, every OS and shell (Node 18+). Installs the NEO App skill for your coding
+agent, registers the `neo-app` MCP server, and authenticates. Idempotent — safe to
+re-run. Targets **production** by default.
+
+```bash
+npx -y @biznetgio/neo-app@latest agent setup
+```
+
+For the **staging** deployment, use its explicit form:
+
+```bash
+NODE_ENV=development npx -y @biznetgio/neo-app@latest agent setup --staging
+```
+
+If the prompt that sent you here named a project id, link it in the same step:
+
+```bash
+npx -y @biznetgio/neo-app@latest agent setup --project <project-id>
+```
+
+## 2. Authenticate (human step)
+
+`agent setup` runs this when no credential is stored. The human provides their NEO App
+API key when prompted — create one in the portal under **Settings → API tokens**.
+The CLI reads it directly and stores it user-only (`~/.config/neo-app/credentials.json`,
+mode 0600); it never lands in agent/MCP configuration. Relay the portal link to the
+human and let them create and paste the key into the CLI prompt — do not ask them to
+paste it into the chat.
+
+```bash
+npx -y @biznetgio/neo-app@latest login            # interactive (prompts for the key)
+```
+
+Headless (VM, SSH, CI): set `NEO_APP_TOKEN=kap_...` and pass `--yes` — the key is read
+from the environment and never written to disk.
+
+## 3. Create or link a project
+
+Pick one. Creating is the default for a fresh repo; link when the human names an existing
+project.
+
+```bash
+npx -y @biznetgio/neo-app@latest link <project-id>   # existing project
+npx -y @biznetgio/neo-app@latest project list        # find project ids
+```
+
+## 4. Verify
+
+```bash
+npx -y @biznetgio/neo-app@latest status              # account, org, environment, linked project
+npx -y @biznetgio/neo-app@latest agent doctor        # CLI, API, auth, MCP wiring, skill, perms
+```
+
+Restart your coding agent so it loads the MCP server, then call the `neo_whoami` MCP
+tool. Report the connected account, organization, environment, detected agent
+integrations, and any unresolved errors. **Do not deploy unless the human separately
+asked for a deployment.**
+
+## Environment
+
+Staging is `https://portal.neoapp.biznetgio.dev`; production is
+`https://portal.app.neoapp.id`. Production is the default; `NODE_ENV=development` or
+`--staging` targets staging; `NEO_APP_URL` overrides the control-plane entirely.
+
+## Uninstall
+
+```bash
+npx -y @biznetgio/neo-app@latest agent uninstall
+```
+
+Removes only the files and configuration NEO App created.
+
+## Safety
+
+Do not disable your agent's sandboxing, approval prompts, or TLS verification to
+complete setup. Production, scaling, public-endpoint and paid-resource actions stay
+subject to NEO App's server-side approval policy — a `pending_approval` result is that
+policy working, not an error.

package/src/agents.js

@@ -0,0 +1,149 @@
+// Detect supported coding agents and register/unregister the `neo-app` MCP server in
+// their config — idempotently, backing up first, and WITHOUT ever writing a token.
+//
+// Codex:       ~/.codex/config.toml   -> [mcp_servers.neo-app]   (TOML)
+// Claude Code: ~/.claude.json         -> mcpServers["neo-app"]   (JSON, user scope)
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { onPath, backupFile } from './util.js';
+
+const MCP_NAME = 'neo-app';
+
+export function agentDefs() {
+  return [
+    { id: 'codex', name: 'Codex', bin: 'codex', configPath: join(homedir(), '.codex', 'config.toml') },
+    { id: 'claude-code', name: 'Claude Code', bin: 'claude', configPath: join(homedir(), '.claude.json') },
+  ];
+}
+
+// detectAgents marks each agent present if its config file exists OR its CLI is on PATH.
+export function detectAgents() {
+  return agentDefs().map((a) => ({ ...a, present: existsSync(a.configPath) || onPath(a.bin) }));
+}
+
+// mcpLaunchSpec picks how the agent should start the MCP server: the installed
+// `neo-app` binary if present, else npx (works with the npx-only install path). The
+// env block carries only the non-secret target (NEO_APP_ENV / NEO_APP_URL); the API
+// key is read at runtime from the credential store, never placed here.
+export function mcpLaunchSpec({ env, url }) {
+  const spec = onPath('neo-app')
+    ? { command: 'neo-app', args: ['mcp'] }
+    : { command: 'npx', args: ['-y', '@biznetgio/neo-app@latest', 'mcp'] };
+  spec.env = url ? { NEO_APP_URL: url } : { NEO_APP_ENV: env };
+  return spec;
+}
+
+// ---- Codex (TOML) ----------------------------------------------------------
+
+export function codexBlock(spec) {
+  const argsToml = JSON.stringify(spec.args); // JSON array is valid TOML array of strings
+  const envPairs = Object.entries(spec.env)
+    .map(([k, v]) => `${k} = ${JSON.stringify(v)}`)
+    .join(', ');
+  return [
+    `[mcp_servers.${MCP_NAME}]`,
+    `command = ${JSON.stringify(spec.command)}`,
+    `args = ${argsToml}`,
+    `env = { ${envPairs} }`,
+  ].join('\n');
+}
+
+// spliceTomlSection replaces (or appends) the [mcp_servers.neo-app] block. The block
+// runs from its header to the next top-level `[...]` header or EOF. Uses an inline
+// env table so the block is a single contiguous section (no sub-headers to track).
+export function spliceTomlSection(content, block) {
+  const lines = content.split('\n');
+  const start = lines.findIndex((l) => /^\s*\[mcp_servers\.neo-app\]\s*$/.test(l));
+  if (start === -1) {
+    const sep = content.trim() ? '\n\n' : '';
+    return `${content.replace(/\s*$/, '')}${sep}${block}\n`;
+  }
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[/.test(lines[end])) end += 1;
+  const before = lines.slice(0, start).join('\n').replace(/\s*$/, '');
+  const after = lines.slice(end).join('\n').replace(/^\s*/, '');
+  return [before, block, after].filter((s) => s.length).join('\n\n').replace(/\s*$/, '') + '\n';
+}
+
+function writeCodex(configPath, spec) {
+  mkdirSync(join(configPath, '..'), { recursive: true });
+  const existing = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  const bak = backupFile(configPath);
+  writeFileSync(configPath, spliceTomlSection(existing, codexBlock(spec)));
+  return { bak };
+}
+
+function removeCodex(configPath) {
+  if (!existsSync(configPath)) return { removed: false, bak: null };
+  const content = readFileSync(configPath, 'utf8');
+  if (!/^\s*\[mcp_servers\.neo-app\]\s*$/m.test(content)) return { removed: false, bak: null };
+  const bak = backupFile(configPath);
+  const lines = content.split('\n');
+  const start = lines.findIndex((l) => /^\s*\[mcp_servers\.neo-app\]\s*$/.test(l));
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[/.test(lines[end])) end += 1;
+  const out = [...lines.slice(0, start), ...lines.slice(end)].join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '') + '\n';
+  writeFileSync(configPath, out);
+  return { removed: true, bak };
+}
+
+// ---- Claude Code (JSON) ----------------------------------------------------
+
+function writeClaude(configPath, spec) {
+  let data = {};
+  if (existsSync(configPath)) {
+    try {
+      data = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      throw new Error(`${configPath} is not valid JSON — fix or remove it, then retry`);
+    }
+  }
+  const bak = backupFile(configPath);
+  data.mcpServers = data.mcpServers || {};
+  data.mcpServers[MCP_NAME] = { command: spec.command, args: spec.args, env: spec.env };
+  mkdirSync(join(configPath, '..'), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(data, null, 2) + '\n');
+  return { bak };
+}
+
+function removeClaude(configPath) {
+  if (!existsSync(configPath)) return { removed: false, bak: null };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return { removed: false, bak: null };
+  }
+  if (!data.mcpServers || !data.mcpServers[MCP_NAME]) return { removed: false, bak: null };
+  const bak = backupFile(configPath);
+  delete data.mcpServers[MCP_NAME];
+  writeFileSync(configPath, JSON.stringify(data, null, 2) + '\n');
+  return { removed: true, bak };
+}
+
+// registerMcp writes the neo-app MCP entry for one agent. Returns { bak }.
+export function registerMcp(agent, spec) {
+  if (agent.id === 'codex') return writeCodex(agent.configPath, spec);
+  if (agent.id === 'claude-code') return writeClaude(agent.configPath, spec);
+  throw new Error(`unknown agent: ${agent.id}`);
+}
+
+export function unregisterMcp(agent) {
+  if (agent.id === 'codex') return removeCodex(agent.configPath);
+  if (agent.id === 'claude-code') return removeClaude(agent.configPath);
+  throw new Error(`unknown agent: ${agent.id}`);
+}
+
+// hasMcp reports whether the neo-app MCP entry is already present (for doctor).
+export function hasMcp(agent) {
+  if (!existsSync(agent.configPath)) return false;
+  const content = readFileSync(agent.configPath, 'utf8');
+  if (agent.id === 'codex') return /^\s*\[mcp_servers\.neo-app\]\s*$/m.test(content);
+  try {
+    return !!JSON.parse(content).mcpServers?.[MCP_NAME];
+  } catch {
+    return false;
+  }
+}

package/src/api.js

@@ -0,0 +1,76 @@
+// Thin REST client for the NEO App control-plane. Auth is a single scheme:
+//   Authorization: Bearer <kap_ token>   (confirmed in pkg/api/middleware.go)
+// All routes are under /api/v1. A 202 + {status:"pending_approval"} is a normal
+// result (org approval policy), NOT an error, so only >=400 throws.
+
+export class ApiError extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class NeoApi {
+  constructor({ baseUrl, token }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.token = token;
+  }
+
+  async request(method, path, { query, body, accept } = {}) {
+    let url = this.baseUrl + path;
+    if (query) {
+      const qs = new URLSearchParams(
+        Object.entries(query).filter(([, v]) => v !== undefined && v !== null)
+      ).toString();
+      if (qs) url += `?${qs}`;
+    }
+    const headers = { Accept: accept || 'application/json' };
+    if (this.token) headers.Authorization = `Bearer ${this.token}`;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    const ctype = res.headers.get('content-type') || '';
+    const isJson = ctype.includes('application/json');
+    const payload = isJson ? await res.json().catch(() => null) : await res.text();
+
+    if (res.status >= 400) {
+      const msg = (isJson && payload && payload.error) || res.statusText || `HTTP ${res.status}`;
+      throw new ApiError(res.status, msg, payload);
+    }
+    return { status: res.status, data: payload };
+  }
+
+  get(path, opts) {
+    return this.request('GET', path, opts);
+  }
+  post(path, body, opts) {
+    return this.request('POST', path, { ...opts, body });
+  }
+  put(path, body, opts) {
+    return this.request('PUT', path, { ...opts, body });
+  }
+  del(path, opts) {
+    return this.request('DELETE', path, opts);
+  }
+
+  // whoami composes the two calls the server needs for identity (no combined endpoint).
+  async whoami() {
+    const me = (await this.get('/api/v1/auth/me')).data;
+    const orgs = (await this.get('/api/v1/orgs')).data?.organizations || [];
+    return { user: me, orgs };
+  }
+
+  // resolveOrgId returns the preferred org id, or the first org the user belongs to.
+  async resolveOrgId(preferred) {
+    if (preferred) return preferred;
+    const orgs = (await this.get('/api/v1/orgs')).data?.organizations || [];
+    if (!orgs.length) throw new ApiError(404, 'no organizations for this account');
+    return orgs[0].id;
+  }
+}

package/src/commands/deploy.js

@@ -0,0 +1,118 @@
+// `neo-app deploy` — create-or-reuse a web service in the linked project and ship it,
+// then poll until the deployment reaches a terminal state (parity with `insta deploy`).
+// Sources: --image <ref> (prebuilt, no build) or --repo <git-url> (server builds it).
+
+import { basename } from 'node:path';
+import { resolveConfig } from '../config.js';
+import { getCredential } from '../creds.js';
+import { NeoApi } from '../api.js';
+import { readLink } from '../link.js';
+import { log, ok, fail, step, c } from '../util.js';
+
+function sanitizeName(s) {
+  return (
+    String(s)
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 60) || 'app'
+  );
+}
+
+function pending(res) {
+  return res.status === 202 && res.data && res.data.status === 'pending_approval';
+}
+
+export async function deploy(opts = {}) {
+  const cfg = resolveConfig(opts);
+  const cred = getCredential(cfg.baseUrl);
+  if (!cred?.token) {
+    fail(`not authenticated for ${cfg.baseUrl} — run 'neo-app login'`);
+    process.exit(1);
+  }
+  const api = new NeoApi({ baseUrl: cfg.baseUrl, token: cred.token });
+
+  const projectId = opts.project || readLink()?.projectId;
+  if (!projectId) {
+    fail("no project — run 'neo-app link <project-id>' or pass --project <id>");
+    process.exit(1);
+  }
+
+  const image = opts.image;
+  const repo = opts.repo;
+  if (!image && !repo) {
+    fail('specify a source: --image <ref> or --repo <git-url>');
+    process.exit(2);
+  }
+
+  const name = sanitizeName(
+    opts.name || (image ? image.split('/').pop().split(':')[0] : basename(repo, '.git'))
+  );
+  const environment = cfg.env === 'staging' ? 'staging' : 'production';
+
+  log(`${c.bold('Deploying')} ${name} ${c.dim(`→ ${cfg.env} · project ${projectId}`)}`);
+
+  // Create-or-reuse the service by name.
+  const existing = (await api.get(`/api/v1/projects/${projectId}/apps`)).data?.applications || [];
+  let app = existing.find((a) => a.name === name);
+
+  if (!app) {
+    const res = await api.post(`/api/v1/projects/${projectId}/apps`, {
+      name,
+      environment,
+      serviceType: 'web',
+      buildType: image ? 'image' : opts.build || 'railpack',
+      image: image || undefined,
+      repoUrl: repo || undefined,
+      branch: opts.branch || undefined,
+      port: opts.port ? Number(opts.port) : undefined,
+      tls: true,
+    });
+    if (pending(res)) {
+      ok(`create submitted — pending approval (${res.data.approvalId}). An owner/admin must approve, then re-run.`);
+      return;
+    }
+    app = res.data?.application || res.data;
+    ok(`created service ${name}`);
+  } else {
+    step(`service ${name} exists — redeploying`);
+    if (image && app.image !== image) await api.put(`/api/v1/apps/${app.id}`, { image });
+  }
+
+  // Ship it.
+  const dep = await api.post(`/api/v1/apps/${app.id}/deploy`);
+  if (pending(dep)) {
+    ok(`deploy submitted — pending approval (${dep.data.approvalId}).`);
+    return;
+  }
+  const deployId = dep.data?.id;
+  step(`deployment ${deployId} started`);
+
+  const result = await pollDeployment(api, deployId, Number(opts.timeout) || 300);
+
+  const view = (await api.get(`/api/v1/apps/${app.id}`)).data?.application || {};
+  const url = view.domain ? `https://${view.domain}` : '';
+  if (result === 'success') {
+    ok(`deployed ${name}${url ? ' → ' + c.bold(url) : ''}`);
+  } else {
+    fail(`deployment ${result}${deployId ? ` (neo-app logs via 'neo_get_logs' or the portal)` : ''}`);
+    process.exitCode = 1;
+  }
+  return { appId: app.id, url, result };
+}
+
+async function pollDeployment(api, id, timeoutSec) {
+  if (!id) return 'unknown';
+  const deadline = Date.now() + timeoutSec * 1000;
+  let last = '';
+  while (Date.now() < deadline) {
+    const d = (await api.get(`/api/v1/deployments/${id}`)).data || {};
+    if (d.status && d.status !== last) {
+      step(`  ${d.status}`);
+      last = d.status;
+    }
+    if (d.status === 'success' || d.status === 'failed') return d.status;
+    await new Promise((r) => setTimeout(r, 4000));
+  }
+  return 'timeout';
+}

package/src/commands/doctor.js

@@ -0,0 +1,86 @@
+// `neo-app agent doctor` — validate the whole setup and give actionable results.
+
+import { resolveConfig } from '../config.js';
+import { getCredential, storeInfo } from '../creds.js';
+import { NeoApi } from '../api.js';
+import { detectAgents, hasMcp } from '../agents.js';
+import { installedSkillVersion, skillVersion } from '../skill.js';
+import { readLink } from '../link.js';
+import { ok, fail, warn, onPath, c, log } from '../util.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+function pkgVersion() {
+  try {
+    const p = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return JSON.parse(readFileSync(p, 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+export async function doctor(opts = {}) {
+  const cfg = resolveConfig(opts);
+  let failures = 0;
+  const bad = (m) => { failures += 1; fail(m); };
+
+  ok(`CLI ${pkgVersion()}`);
+
+  // API reachability + TLS (open root endpoint, no auth)
+  try {
+    const res = await fetch(`${cfg.baseUrl}/healthz`);
+    if (res.ok) ok(`API ${cfg.baseUrl}`);
+    else bad(`API ${cfg.baseUrl} returned HTTP ${res.status}`);
+  } catch (e) {
+    bad(`API ${cfg.baseUrl} unreachable: ${e.message}`);
+  }
+
+  // Auth
+  const cred = getCredential(cfg.baseUrl);
+  let who = null;
+  if (!cred?.token) {
+    bad(`not authenticated for ${cfg.env} — run 'neo-app login'`);
+  } else {
+    try {
+      who = await (new NeoApi({ baseUrl: cfg.baseUrl, token: cred.token })).whoami();
+      ok(`authenticated as ${who.user?.email || who.user?.name}`);
+    } catch (e) {
+      bad(`token invalid: ${e.message}`);
+    }
+  }
+
+  // Org / project / env
+  const org = who?.orgs?.[0];
+  if (org) ok(`org ${org.name} (${org.role})`);
+  const link = readLink();
+  if (link?.projectId) ok(`project ${link.name || link.projectId} / ${link.environment}`);
+  else warn(`no linked project (optional) — 'neo-app agent setup --project <id>'`);
+
+  // Agents + MCP
+  for (const a of detectAgents()) {
+    if (!a.present) { warn(`${a.name} not detected`); continue; }
+    if (hasMcp(a)) ok(`${a.name} MCP configured`);
+    else bad(`${a.name} detected but neo-app MCP not configured — run 'neo-app config install-mcp'`);
+  }
+
+  // Skill
+  const installed = installedSkillVersion();
+  if (!installed) bad(`skill not installed — run 'neo-app agent setup'`);
+  else if (installed !== skillVersion()) warn(`skill ${installed} installed; ${skillVersion()} available — rerun setup`);
+  else ok(`skill ${installed}`);
+
+  // Credential file permissions
+  const info = storeInfo();
+  if (cred?.source === 'env') ok('credentials from NEO_APP_TOKEN (env)');
+  else if (!info.exists) warn('no credential file');
+  else if (info.secure) ok(`credentials file user-only (${info.path})`);
+  else bad(`credentials file is not 0600 (${info.mode}) — run 'chmod 600 ${info.path}'`);
+
+  // Required executables
+  onPath('npx') ? ok('npx available') : warn("npx not found — needed for the npx install path");
+
+  log('');
+  if (failures) { fail(`${failures} check(s) failed`); process.exitCode = 1; }
+  else log(c.green('All checks passed.'));
+}