Neb Env Setup

If the user provides different values during setup, update the .env file accordingly.

Step 1: Check Existing .env

Read the .env file at the repo root ($REPO_ROOT/.env where $REPO_ROOT is determined by git rev-parse --show-toplevel).

• If the file exists, parse all existing NEB_TASK_* variables and preserve their values as defaults.
• If it does not exist, start with empty defaults.

Store these as the current state:

NEB_TASK_API_URL=<existing or empty>
NEB_TASK_COMPANY_ID=<existing or empty>
NEB_TASK_PREFIX=<existing or empty>
NEB_TASK_AGENT_ID=<existing or empty>
NEB_TASK_API_KEY=<existing or empty>

Step 2: Determine API URL

If NEB_TASK_API_URL is already set, show the current value and ask if the user wants to keep it.

If not set, use AskUserQuestion to prompt:

Platform instance URL? This is the URL where your task management platform is running. Default: http://127.0.0.1:3101 Press Enter to accept the default, or enter a custom URL.

If the user provides no input or confirms the default, use http://127.0.0.1:3101.

Store the result as API_URL.

Step 3: Detect Deployment Mode

Determine whether the instance is local (direct Paperclip) or remote (platform-backend proxy):

• Local: API URL contains 127.0.0.1 or localhost — Paperclip API is accessed directly at /api/*
• Remote: Any other URL (e.g., https://api.nebcore.ai) — Paperclip API is behind platform-backend proxy at /api/v1/orgs/{companyId}/ai/*

Store as DEPLOY_MODE (local or remote).

Step 4: Health Check

Health check depends on deployment mode:

Local mode:

curl -sf --max-time 5 "${API_URL}/api/health"

Remote mode (platform-backend):

# Platform liveness probe — no auth required
curl -sf --max-time 5 "${API_URL}/healthz"

Then, if NEB_TASK_API_KEY and NEB_TASK_COMPANY_ID are already set, also verify the AI server is reachable through the proxy:

curl -sf --max-time 5 "${API_URL}/api/v1/orgs/${NEB_TASK_COMPANY_ID}/ai/health" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

Expected response: JSON with {"status":"ok",...}

If the health check fails, report the error and provide troubleshooting guidance:

ERROR: Cannot reach the platform at ${API_URL}

Troubleshooting:
  1. Verify the platform is running
  2. Local: confirm port matches (default: 3101)
  3. Remote: /healthz should respond without auth
  4. If API key is set, verify AI server health via proxy:
     curl ${API_URL}/api/v1/orgs/{companyId}/ai/health -H "Authorization: Bearer $KEY"

Run /neb-env-setup again once the platform is accessible.

STOP here if health check fails. Do not proceed.

Step 5: Fetch Companies

How to list companies depends on deployment mode:

Local mode (direct Paperclip, local_trusted — no auth needed):

curl -sf --max-time 5 "${API_URL}/api/companies"

Remote mode (platform-backend proxy — requires JWT auth):

The AI proxy path requires a company ID to construct the URL, creating a bootstrap problem. Handle it as follows:

1. If NEB_TASK_COMPANY_ID and NEB_TASK_API_KEY are already in .env, verify them:

curl -sf --max-time 5 "${API_URL}/api/v1/orgs/${NEB_TASK_COMPANY_ID}/ai/companies/${NEB_TASK_COMPANY_ID}" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

2. If no company ID is set, try decoding the JWT to extract it:

echo "$NEB_TASK_API_KEY" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin).get('company_id',''))"

3. If no JWT exists either, prompt the user for their company ID (they can find it in the platform dashboard).

Expected response: JSON company object with id, name, and issuePrefix fields.

If zero companies are returned or validation fails:

ERROR: No companies found or company not accessible.
For remote instances, ensure you have a valid API key with company access.

STOP here.

If exactly one company exists (local mode): Auto-select it. Print:

Found company: <name> (prefix: <issuePrefix>)
Using this as your active company.

If multiple companies exist (local mode): Use AskUserQuestion to prompt the user to select:

Multiple companies found. Which one should be your active company?

1. <name1> (prefix: <prefix1>)
2. <name2> (prefix: <prefix2>) ...

Enter the number of your choice:

Step 6: Extract Company Details

From the selected/verified company object, extract:

• COMPANY_ID = the id field
• PREFIX = the issuePrefix field

Step 7: Validate Company Access

Confirm access by fetching the specific company:

Local mode:

curl -sf --max-time 5 "${API_URL}/api/companies/${COMPANY_ID}"

Remote mode:

curl -sf --max-time 5 "${API_URL}/api/v1/orgs/${COMPANY_ID}/ai/companies/${COMPANY_ID}" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

If this fails, report the error and stop.

Step 8: Write .env File

Write the .env file at the repo root. Preserve any existing NEB_TASK_AGENT_ID and NEB_TASK_API_KEY values if they were already set (these are populated by /neb-work).

The .env file content:

# Task Management Platform — connection credentials
# Generated by /neb-env-setup on <current date>
# Agent credentials are set by /neb-work

NEB_TASK_API_URL=<API_URL>
NEB_TASK_COMPANY_ID=<COMPANY_ID>
NEB_TASK_PREFIX=<PREFIX>
NEB_TASK_AGENT_ID=<existing value or empty>
NEB_TASK_API_KEY=<existing value or empty>

IMPORTANT: If the .env file contained other non-NEB_TASK_* variables, preserve them at the end of the file under a # Other settings comment.

Step 9: Print Success

Print a clear success message:

Environment setup complete.

  API URL:    <API_URL>
  Company:    <company name>
  Company ID: <COMPANY_ID>
  Prefix:     <PREFIX>
  Deploy Mode:<local or remote>
  Agent ID:   <set or "not set — run /neb-work to configure">
  API Key:    <set or "not set — run /neb-work to configure">

.env written to: <repo_root>/.env

Next steps:
  - Run /neb-work to register as an agent and get API credentials
  - Then use /neb-task-exe, the platform orchestrator, etc. to work on tasks

Error Handling

• All curl commands use --max-time 5 to avoid hanging on unreachable hosts.
• Use -sf (silent + fail) so non-2xx responses are treated as errors.
• Parse JSON responses with python3 -c "import sys,json; ..." for reliability.
• If any step fails, print a clear error message and STOP. Do not write a partial .env.

Rules

• NEVER call the AI server directly via kubectl exec, port-forward, or localhost. All API calls to the AI server MUST go through the platform-backend AI proxy at ${NEB_TASK_API_URL}/api/v1/orgs/${NEB_TASK_COMPANY_ID}/ai/*.
• NEVER hardcode the name of any specific task management product in user-facing messages. Use "task management platform" or "platform instance" instead.
• All environment variables use the NEB_TASK_ prefix.
• The .env file lives at the repo root only — never in subdirectories.
• Preserve existing values that are not being changed (especially agent credentials).
• Use AskUserQuestion for all interactive prompts — never assume user input.