Setup Issues

Installation problems

Setup Issues

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Problems during AIWG installation or project setup.

AIWG Installation Not Found

Symptoms: "AIWG not found", "the agent-owned command operation not found"

Cause: AIWG CLI not installed or not in PATH.

Solution:

Use AIWG to complete this documented outcome: Solution
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Bleeding edge: `curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash`

Installation Path Issues

Symptoms: Commands work but templates/agents not found.

Cause: AIWG installed in non-standard location.

Solution:

Use AIWG to complete this documented outcome: Solution
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

If you intentionally changed Node managers, npm prefixes, Homebrew ownership, or installation roots, make that change explicit with the agent-owned installation operation. To return to another installation, use the agent-owned installation operation and include `the manager option <absolute-path>` for npm/source. Then run the agent-owned doctor operation.

Do not repair drift only by reordering `PATH`: updates intentionally remain bound to the recorded package manager until an explicit adopt or switch.

Corrupt Installation

Symptoms: Partial files, missing directories, strange errors.

Cause: Interrupted install or git issues.

Solution:

Use AIWG to complete this documented outcome: Solution
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Permission Denied

Symptoms: `Permission denied`, `EACCES`, or an npm error like:

npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/aiwg

Cause: npm is trying to install global packages into a system-owned directory. This is common on macOS when Node.js was installed with an installer or an older global npm setup.

Solution:

Preferred macOS fix: use `nvm` and reinstall AIWG under a user-owned Node.js install. See macOS Install Guide.

If Node is already installed and you want the shortest recovery path, use npm's current user-owned global prefix:

Use AIWG to complete this documented outcome: If Node is already installed and you want the shortest recovery path, use npm's current user-owned global prefix
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Do not use `sudo the agent-assisted AIWG installation procedure` as the default fix. It can leave root-owned npm files that break later upgrades.

Shell Alias Not Working

Symptoms: `aiwg` command not found after install.

Cause: Shell aliases not loaded.

Solution:

# For bash
source ~/.bash_aliases
# Or
source ~/.bashrc

# For zsh
source ~/.zshrc

# Verify alias exists
alias aiwg