apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata:
  name: aiwg
  description: Safely install, repair, update, connect, and verify AIWG for a supported provider.
  version: "1.0.0"
  install_type: user
  execution_mode: provider-orchestrated
spec:
  platforms:
    - os: linux
      shell: bash
    - os: linux
      shell: wsl2
    - os: macos
      shell: zsh
    - os: windows
      shell: native
  params:
    - name: PROJECT_DIR
      type: path
      required: true
      description: The project folder where AIWG should be connected.
    - name: PROVIDER
      type: choice
      required: true
      description: The agentic provider that will use AIWG in this project.
      choices:
        - claude
        - codex
        - copilot
        - cursor
        - factory
        - grokbot
        - hermes
        - muse
        - openclaw
        - opencode
        - openhuman
        - warp
        - devin
        - windsurf
  steps:
    - id: explain-and-confirm
      type: agentic
      instruction: >-
        Explain in plain language that this flow will inspect the machine and project
        before making changes. Infer PROJECT_DIR from the open workspace and PROVIDER
        from the current agent when reliable; ask the user only when either is ambiguous.
        Explain the difference between a terminal and an agent conversation if that
        would help. Do not request passwords, tokens, or pasted secrets. Do not make
        changes yet.
    - id: inspect-existing-state
      type: agentic
      depends_on:
        - explain-and-confirm
      instruction: >-
        Perform a read-only inspection of the operating system, architecture, current
        shell, PATH, Node.js, npm, installed Node version managers, global npm prefix,
        every resolvable aiwg executable, npm global aiwg and @aiwg/cli packages,
        AIWG_ROOT and related AIWG environment variables, and PROJECT_DIR. Detect
        shadowed or duplicate binaries, system-owned npm prefixes, versions older than
        Node 20, stale or broken AIWG packages, package/version mismatches, and provider
        files already deployed in the project. Also detect an empty/new project,
        a non-Git folder, a monorepo or nested workspace, read-only filesystems,
        low disk space, offline/proxy/registry restrictions, and concurrent package
        manager or AIWG processes. Run an existing aiwg doctor and
        aiwg status --probe --json only when the resolved executable can be invoked
        safely. Never use sudo to repair a global npm installation.
    - id: detect-development-mode
      type: agentic
      depends_on:
        - inspect-existing-state
      instruction: >-
        Determine whether AIWG is intentionally running from a source checkout,
        npm link, workspace link, local file dependency, custom AIWG_ROOT, or a
        repository command such as node bin/aiwg.mjs. Treat this as development mode,
        not as a broken published install. Report the checkout path, Git branch,
        worktree cleanliness, configured remotes, and whether the branch is behind its
        upstream using read-only Git operations. Never pull, switch branches, discard
        changes, unlink a package, or replace development mode without explicit user
        approval.
    - id: propose-remediation
      type: agentic
      depends_on:
        - detect-development-mode
      instruction: >-
        Summarize the inspection in ordinary language and propose the smallest safe
        plan. Reuse a healthy existing Node version manager. Do not stack managers.
        AIWG requires Node 24 or newer; use Node 24 for a new install.
        If Node is missing or unsuitable, offer an official version-manager path:
        nvm-sh for macOS, Linux, or WSL and nvm-windows for native Windows. Explain any
        required new shell or PATH refresh before proceeding. If development mode is
        active, offer two explicit choices: stay in development mode and safely update
        the checkout after preserving a dirty worktree, or switch to the published
        aiwg package after explaining which links and environment settings would
        change. Preserve development mode by default. If a published install is stale
        or broken, propose repairing or updating the full aiwg package. Explain any
        duplicate or shadowed binaries and identify the exact paths affected. Obtain
        approval before any installation, update, unlink, PATH/profile edit, Git pull,
        or provider-file mutation. If more than one provider is requested, explain
        that guided apply and deployment verification must cover every selected provider.
        If the environment is CI, headless, a container, SSH-only, offline, or
        read-only, stop using this interactive manifest and route to the documented
        non-interactive or offline bootstrap flow instead of improvising prompts or mutations.
        After a healthy CLI is available, guided setup accepts the same answers as
        flags with --non-interactive, and headless apply requires --yes.
    - id: repair-or-install
      type: agentic
      depends_on:
        - propose-remediation
      instruction: >-
        Carry out only the approved plan. For published mode, install or update the
        full local-corpus package with npm install --global aiwg and verify that the
        selected aiwg executable and npm package version agree. Do not install
        @aiwg/cli as the new-user default. For development mode, keep using the
        checkout unless the user explicitly chose to switch; update it only with a
        non-destructive Git operation that preserves local work, then use the
        repository's documented install/build commands. Correct stale PATH entries,
        links, or duplicate packages only when the user approved those exact changes.
        Stop and explain if a required operation would overwrite work or needs
        administrator access.
      on_fail: diagnose-install
    - id: guided-interview
      type: agentic
      depends_on:
        - repair-or-install
      instruction: >-
        From PROJECT_DIR, run the healthy CLI with aiwg setup --scope project
        --providers PROVIDER to record the guided interview plan. Ask about targets,
        intent, providers, configuration locations, and optional capabilities. Use
        --scope user only when that provider scope was explicitly selected; global
        npm installation and provider scope are separate decisions. Confirm monorepo
        root versus an observed package before applying. Scan additional directories
        only by explicit opt-in. Preserve existing answers and settings. Plans save
        credential references, never secrets; accept env:NAME, file:absolute-path,
        or stdin references. The interview writes no provider configuration. Jev and
        direct workers remain optional and require explicit opt-in. Explain Jev's
        external service/account and usage charges, and worker account quotas and
        installed-versus-qualified state. Interactive cancel retains the last saved
        plan. For headless operation, provide the same choices as flags with
        --non-interactive; never prompt or invent a required missing answer.
    - id: guided-review
      type: agentic
      depends_on:
        - guided-interview
      instruction: >-
        Run aiwg setup --review from PROJECT_DIR to inspect the saved plan without
        writes. Explain selected workspaces, providers, scope, framework, optional
        integrations, conflicts, stale facts, missing references, and affected files.
        A bare aiwg setup --dry-run also reviews an existing saved plan. Use --json
        when structured review output is needed. Obtain approval for the concrete
        plan before apply. Re-run the interview when discovery facts are stale or
        choices need changing; do not force past scope conflicts or overwrite
        project-authored files. Guided intent selects sdlc for code/mixed, writing
        for docs, and ops for ops; aiwg use all --provider PROVIDER --json remains
        available for a direct complete-system deployment outside the guided plan.
    - id: apply-guided-plan
      type: agentic
      depends_on:
        - guided-review
      instruction: >-
        Run aiwg setup --apply for the approved saved plan. In headless operation,
        use aiwg setup --apply --yes --non-interactive --json only after approval.
        Apply delegates to existing configuration, deployment, registry, Jev, and
        worker qualification owners and saves a receipt after each action. A fully
        successful repeat apply makes no writes; after partial failure or
        interruption, review and reapply only unfinished actions. If an external
        side effect occurred before its receipt was saved, inspect that owner
        before retrying. Never initialize Git or create a new project structure
        unless explicitly requested.
      on_fail: diagnose-install
    - id: verify-engagement
      type: agentic
      depends_on:
        - apply-guided-plan
      instruction: >-
        Inspect aiwg.setup.apply.v1 from guided apply: classification, action status,
        workspace/provider, and core versus optional failures. A partial result means
        core setup applied while an optional action failed or was skipped; report it
        honestly and preserve the plan for retry. A failure means core setup is not
        ready. Successful deployment actions consume aiwg.use.result.v1 verification
        through the existing owner. Check every selected provider and verify that
        the current agent can read the resulting bootstrap and discover a capability.
        Do not make index, regenerate, status, or doctor commands mandatory follow-up
        steps. Use aiwg status --probe --json or aiwg doctor only for a requested
        audit or an indicated recovery action. Explain any actual reload requirement.
      on_fail: diagnose-install
    - id: session-handoff
      type: agentic
      depends_on:
        - verify-engagement
      instruction: >-
        If the current provider can read the regenerated files and discover AIWG,
        continue in the same session and clearly say that no restart is needed. Ask
        the user to reload or restart the provider only if verification shows that
        the provider is caching old startup instructions or cannot discover the new
        adapter. Explain why, ask the user to restart, and give them this exact resume
        prompt: "Continue the AIWG setup verification in this project. Run aiwg status
        --probe --json and tell me whether AIWG is engaged." Do not claim success until
        the verification evidence passes.
  recovery:
    - id: diagnose-install
      steps:
        - id: collect-safe-diagnostics
          type: agentic
          instruction: >-
            Stop mutations. Preserve the failing command and useful error text without
            exposing secrets. Re-run only read-only version, PATH, npm prefix, AIWG
            doctor, status, Git state, and file-existence checks relevant to the
            failure. Explain the likely cause and propose the smallest reversible
            correction. Obtain approval before retrying any mutation. Never delete a
            source checkout, project-authored instructions, npm cache, or user data as
            a generic recovery step.
  briefing:
    success: >-
      AIWG is installed or repaired, the guided interview plan was reviewed and
      applied, and the readiness report identifies verified core setup for each
      selected provider plus the outcome of every selected optional integration.
    next_steps:
      - Ask the agent what AIWG can help with in this project.
      - Run aiwg status --probe --json whenever you want evidence that AIWG is engaged.
      - Use aiwg doctor when an install, update, or provider connection behaves unexpectedly.
