# apply.sh — how it works

How `apply.sh` sets up and maintains AI instructions across all projects. See [README.md](README.md) for context and [docs/architecture.md](docs/architecture.md) for design decisions.

## Design constraints

`.ai/` is a symlink in every project, pointing back to `ai-superpower/.ai/`. No files are copied. There are no manually maintained project lists. The script discovers projects automatically by scanning for `.git` directories. Every run is a full scan — idempotent and stateless.

## How apply.sh works

`apply.sh` **must be run via `curl | bash`** from the dev root. Direct invocation is blocked:

```bash
curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash
```

**Bootstrap phase** — when piped through bash, `BASH_SOURCE[0]` is empty. The script uses this to detect the bootstrap context, then clones (or pulls) the repo and re-execs the local `apply.sh --bootstrapped DEV_ROOT`.

**Local phase** — runs with `--bootstrapped` flag. Scans dev root recursively for `.git` directories and runs per-project setup for each one found.

## Project detection

The script scans dev root recursively (`-maxdepth 4`) for directories containing `.git`. Any project with a `.ai-superpower` marker file in its root is excluded — this identifies the ai-superpower repo itself regardless of what the directory is named.

## Per-project actions

For each discovered project:

1. Creates `project/.ai` → `ai-superpower/.ai/` symlink if missing or broken
2. Appends `.ai` to `project/.gitignore` if not already present (creates the file if needed)
3. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it
4. Creates `docs/ai-context.md` from template if missing; refreshes if factory-reset marker is still on line 1
5. Creates `docs/architecture.md` from template if missing; refreshes if factory-reset marker is still on line 1

## Keeping instructions up to date

When instructions in this repo change, just pull:

```bash
cd ~/koodi/ai-superpower
git pull
```

Because `.ai/` is a symlink, all projects see the updated instructions immediately — no re-run of `apply.sh` needed. Run `apply.sh` only when adding new projects or repairing broken symlinks.

`apply.sh` is idempotent — safe to run as many times as needed. Customised `docs/` files (factory-reset marker absent) are never overwritten.

## Adding a new project

The project must be a git repository — `git init` must have been run first. Without a `.git` folder, `apply.sh` will not detect it.

Once initialised, re-run via `curl | bash` from the dev root — it detects the new project automatically. No other configuration needed.

## Project context (ai-context.md)

`docs/ai-context.md` is the AI's window into the project. The script creates a blank template if the file is missing, but the content must reflect the actual project.

Use the AI to create or update it. Open the project in your editor and prompt:

> Read the codebase and create `docs/ai-context.md`. Cover: what this project does, the technology stack, architecture overview, key decisions, and anything the AI needs to know to work here effectively.

For updates after significant changes:

> Review `docs/ai-context.md` against the current codebase. What is outdated or missing?