---
name: gofer:eai-first-run
description: "Prepare a new machine or repo for the first EAI Gofer app build."
title: "EAI First Run"
category: control
surfaces:
  - claude
  - claude-mirror
  - copilot
  - vscode
  - codex
  - gemini
  - github-prompts
  - agents-skills
  - system-skills
aliases: [gofer:first-run, gofer:eai-setup]
---

# EAI Gofer First Run

Use this command when the user is starting their first EAI Platform app, when
`/0_business_scenario` is unavailable in a new repository, or when an EAI app
build reaches the Gofer pipeline before the local machine, workspace, tenant, or
EAI app template is ready.

This command is intentionally allowed to run before `.specify/` exists.

## Non-Negotiables

- Ask before every install, admin action, browser login, destructive file
  change, or remote tenant/app change.
- Never print, store, or commit tokens, secrets, full `.env.local` values,
  private tenant payloads, or private platform topology.
- Prefer existing tools over reinstalling. Keep working Git, Node.js, npm, and
  EAI CLI installations.
- Do not scaffold over a non-empty repo silently.
- Use the EAI Platform app template first, Azure second, and non-EAI stacks only
  by explicit exception.
- In GitHub Codespaces, avoid `sudo` or host-level package installs unless the
  user explicitly approves. Prefer the prebuilt devcontainer and user-level npm.

## Step 1: Identify Host, OS, Shell, And Workspace

Detect and report:

- Host: Claude Code, Codex, GitHub Copilot, Gemini, VS Code, GitHub Codespaces,
  or unknown.
- OS: macOS, Linux, Windows, or Codespaces Linux.
- Shell: bash/zsh, PowerShell, cmd, or unknown.
- Workspace root: current folder, opened editor workspace, Codespace checkout,
  or a folder the user wants to create.

If no suitable folder is open, ask the user where the project should live. If
the host can create the folder, ask approval and create it. If not, give exact
click/command instructions and continue after the folder is open.

## Step 2: Check Developer Prerequisites

Run only safe read/check commands first:

| Tool    | POSIX check                       | PowerShell check                         |
| ------- | --------------------------------- | ---------------------------------------- |
| Git     | `git --version`                   | `git --version`                          |
| Node.js | `node --version`                  | `node --version`                         |
| npm     | `npm --version`                   | `npm --version`                          |
| EAI CLI | `eai --version`                   | `eai --version`                          |
| Registry | `npm config get @eai-tools:registry` | `npm config get @eai-tools:registry` |

If Git, Node.js, or npm is missing, ask before installing. Use the least
surprising platform path:

| Platform            | Preferred install path                                                                 |
| ------------------- | --------------------------------------------------------------------------------------- |
| macOS               | Use Homebrew if already installed; otherwise use the official Git/Node installer path.  |
| Linux               | Prefer existing devcontainer tools; otherwise detect `apt`, `dnf`, `yum`, or `zypper`. |
| Windows             | Prefer `winget`; fall back to the official Git for Windows and Node.js installers.      |
| GitHub Codespaces   | Prefer preinstalled tools and user-level npm; avoid host-level package installs.        |

For Windows, use PowerShell-safe syntax. Do not emit POSIX-only shell redirection
or assume Git Bash exists unless it was detected.

## Step 3: Install Or Update EAI CLI

If `eai` is missing, or if the user asks to update it, ask for approval and run:

```bash
npm config set @eai-tools:registry https://eai-tools.github.io/eai/registry/ --location=user
npm install -g @eai-tools/cli
eai --version
```

Use the same commands in PowerShell. Do not edit `.npmrc` by shell redirection.

If the scoped registry already equals
`https://eai-tools.github.io/eai/registry/`, do not rewrite it. If it points
somewhere else, show the current value and ask before changing it.

If `eai` is already installed, run:

```bash
eai update --check
```

If an update is available, explain the currently installed version versus the
latest available version and ask before running `eai update`.

If install fails, stop EAI app delivery and give the user the exact failed
command, the public setup link, and the account requirement. Continue only if
the user explicitly chooses a non-EAI path.

## Step 4: Discover EAI CLI Capabilities

Run:

```bash
eai --describe
```

If advertised, also run:

```bash
eai agent guide --format json
```

Prefer commands and options advertised by the installed CLI over remembered
syntax. Use JSON only where the CLI advertises it. Record a safe summary in the
first-run report.

When any later `eai` command fails, use the CLI's error guidance before
inventing a workaround:

```bash
eai errors explain <code-or-reason> --format json
```

Specifically note whether the installed CLI advertises the commands needed for:

- app scaffolding via `eai init`
- tenant selection via `eai tenant select`
- app enrollment via `eai vertical`
- resource schema discovery via `eai resources schema`
- workflow readiness via `eai workflow readiness`
- Entra app registration and redirect URI provisioning via `eai provision entra`
- project drift checks via `eai template check`
- Gofer drift checks via `eai gofer refresh --check`
- UI block discovery via `eai blocks`
- AI-agent guidance via `eai agent guide`
- error recovery guidance via `eai errors explain`

## Step 5: Login, Tenant, And Account Readiness

Run:

```bash
eai whoami
eai tenant list --format json
```

If not logged in or the token is expired, ask before running:

```bash
eai login
```

After login, list tenants again. If more than one tenant is available, help the
user choose the correct one and run the advertised equivalent of:

```bash
eai tenant select <tenant-slug-or-id>
```

Require at least one usable tenant membership before EAI app delivery. Prefer a
tenant-admin/operator-capable role because app enrollment and provisioning are
tenant-scoped actions. If no tenant is available, tell the user they need an EAI
Platform account and tenant access before Gofer can build an app.

## Step 6: Confirm Project Folder And Name

Before `eai init`, ask whether the current folder/workspace is the right place.
If the user wants a new sibling or child folder, create it only after approval.

Ask for the project display name. If the user gives a plain-language name,
propose a lowercase kebab-case CLI name and confirm it before continuing.

Collect or confirm:

- App display name
- Lowercase kebab-case app/project name
- One-sentence business description
- Active tenant
- Whether starter defaults should be kept

## Step 7: Initialize The EAI App Template

Detect existing template markers before scaffolding:

- `src/eai.config/object-types.ts`
- `src/eai.config/register.ts`
- `.env.example`
- `.npmrc`
- `package.json`

If the repo already looks like an EAI app, run `eai verify` and continue with
the existing project. If the installed CLI advertises them, also run:

```bash
eai template check --format json
eai gofer refresh --check --format json
```

If `eai verify`, `eai template check`, or `eai doctor --check-updates`
returns `E001` or reports "Not in an EAI project", treat the repo as not yet
initialized from the EAI app template and explain that clearly.

If this is an empty or approved target folder, ask for final confirmation and
run the advertised equivalent of:

```bash
eai init <project-name> --skip-prompts --company-tenant <active-tenant-id>
```

If the CLI requires additional safe answers, gather them first. If the repo is
non-empty and not an EAI app, ask whether to initialize a new sibling EAI app
directory or stop.

## Step 8: Recover Known Entra Redirect Mismatches

If the user provides a browser sign-in error, auth callback log, or deployment
log containing `AADSTS50011`, "reply URL specified in the request does not
match", "redirect URI", `redirect_uri`, or
`/api/auth/callback/microsoft-entra-id`, treat it as an EAI identity
provisioning recovery before giving manual Azure Portal instructions.

Do this sequence:

```bash
eai whoami
eai tenant list --format json
```

If the active tenant is missing or wrong, help the user choose the right tenant
and run the advertised equivalent of:

```bash
eai tenant select <tenant-slug-or-id>
```

Capture the exact callback URI from the failing browser log, for example:

```text
https://<host>/api/auth/callback/microsoft-entra-id
```

Ask before changing tenant-scoped identity configuration, then run the
advertised equivalent of:

```bash
eai provision entra --force --redirect-uri <exact-callback-uri> --debug
```

After the command succeeds, retry the sign-in flow and confirm the authorize
request uses the same registered `redirect_uri`. If the mismatch persists,
check whether `AUTH_ENTRA_CLIENT_ID` or `ENTRA_CLIENT_ID` points to a different
app registration than the one EAI provisioned. Never record client secrets,
tokens, or `.env.local` values in the first-run report.

## Step 9: Confirm Gofer Scaffold And Workspace Commands

After `eai init`, verify Gofer files exist:

- `.specify/.gofer-version`
- `.specify/commands/0_business_scenario.md`
- `.specify/templates/spec-template.md`
- `.specify/scripts/node/gofer-workspace-check.mjs`
- `.specify/memory/gofer-model-policy.yaml`
- `AGENTS.md` or the host-specific instruction file

If the Gofer scaffold is missing or stale, run `/gofer:bootstrap-workspace`
using the current host policy, then rerun:

```bash
node .specify/scripts/node/gofer-workspace-check.mjs --host auto --json
```

If the current host cannot run slash commands yet, use the installed plugin
bundle or downloaded public bundle as the bootstrap source described by
`/gofer:bootstrap-workspace`.

## Step 9: Open Or Attach The Created Project

Make sure the active host is working in the initialized EAI app folder:

- VS Code: open the folder in the current or a new VS Code window when `code`
  is available; otherwise give exact UI steps.
- Codex: show the absolute folder path and ask the user to open that folder as
  the active Codex workspace if the host cannot switch automatically.
- Claude Code: show the absolute folder path and ask the user to attach/open it
  if the host cannot switch automatically.
- Gemini/Copilot in VS Code: ensure the VS Code workspace is the initialized app
  folder before starting Gofer.
- GitHub Codespaces: keep the current Codespace workspace unless the project was
  created in a subfolder; then `cd` into it and report the path.

## Step 10: Write The First-Run Report

Write only to `.specify/logs/eai-first-run-report.md`. If `.specify/` does not
exist yet, create the report after `eai init` or after Gofer bootstrap.

If the target file already exists, replace it and prepend a regeneration note
such as `<!-- regenerated at [ISO timestamp] -->`.

Include the minimum provenance schema:

- `GeneratedAt`
- `SourceCommandId`
- `SourceInputs`
- `OverwriteNoticeWhenApplicable`

The generated first-run report must contain these sections:

- `## Provenance`
- `## Workspace Root`
- `## Environment Check`
- `## EAI CLI`
- `## Tenant And Login`
- `## Template Readiness`
- `## Drift And Recovery`
- `## Next Action`

Each section should include:

- Host, OS, shell, workspace root, and prerequisite tool versions
- Git, Node.js, npm, and EAI CLI versions
- EAI registry status
- EAI CLI release status from `eai update --check`
- EAI CLI capability source (`eai --describe` timestamp)
- EAI capability inventory for init, tenant, vertical, resources, workflow,
  template, Gofer-refresh, and blocks commands
- Login status without tokens
- Tenant readiness without private payloads
- Template readiness
- Template/Gofer drift status, the next recovery command, and any `E001`
  explanation
- Gofer scaffold readiness and project path
- Next action

## Step 11: Start The Pipeline

When the app folder, EAI CLI, login, tenant, EAI template, and Gofer scaffold are
ready, tell the user to start:

```text
/0_business_scenario <what you want to build>
```

If `/0_business_scenario` is still unknown after the plugin is installed and the
repo is bootstrapped, explain that the host has not loaded the Gofer plugin or
repo commands yet. Give the host-specific install/update command from the Gofer
README, then retry this command after the host reloads.
