/init Project Context Command

## Summary

Add a slash-command **`/init`** inside **`q chat`** that scans the current repository (or a supplied path) and generates a reusable project‑context file (default: `Q_CONTEXT.md`). The file is automatically loaded on every future chat session, giving Amazon Q immediate knowledge of the codebase—similar to Claude Code’s `/init`.

## Goals / Acceptance Criteria

| # | Outcome | Acceptance Criteria |
| - | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 1 | **One‑shot setup** | Running `/init` creates or updates a context file in ≤ 30 s for a repo ≤ 20 kLOC. |
| 2 | **Better answers** | Immediately after generation, asking “Explain the repo” yields a context‑aware answer with no manual `/context add`. |
| 3 | **Team reuse** | When the file is committed, any teammate running `q chat` in the repo loads it automatically. |
| 4 | **Staleness guard** | If the HEAD commit differs from the file header, Q warns and suggests `/init --update`. |
| 5 | **No collision** | Existing **shell** `q init` behaviour remains untouched. |

## User Stories

* **US‑1** As a new developer, I can run `/init` to bootstrap Q so I can ask architectural questions without reading the entire codebase.
* **US‑2** As a maintainer, I can re‑run `/init --update` after large refactors to refresh the summary.
* **US‑3** As a CI engineer, I can run `echo '/init --non-interactive' | q chat --stdin` in pipelines to regenerate the file automatically.

## Command Syntax

```
/init [PATH] [--file ] [--append] [--non-interactive] [--update] [--dry-run]
```

| Flag | Description |
| ------------------- | ------------------------------------------------------- |
| `PATH` | Root directory to analyse (defaults to CWD). |
| `--file` | Override output file name (default `Q_CONTEXT.md`). |
| `--append` | Add new sections, keep existing manual edits. |
| `--update` | Regenerate only if stored commit ≠ current HEAD. |
| `--non-interactive` | Run with defaults; print resulting file path to stdout. |
| `--dry-run` | Show diff but do not write to disk. |

## Context‑File Spec (`Q_CONTEXT.md`)

```yaml
---
q-context-version: 1
generated-by: amazon-q-cli 1.x
generated-at: 2025-06-26T18:00:00Z
repo-head:
---
```

Sections (Markdown):

1. Project elevator pitch
2. Directory & package map
3. Build & test commands
4. Coding conventions
5. Architectural patterns / TODOs
6. *Optional*: dependency graph image

## Functional Requirements

1. **Repository Scan** – language detection, respect `.gitignore`, ignore binary/large directories (`node_modules/`, `target/`, etc.).
2. **Token Budget** – cap 8 k tokens; truncate or summarise beyond limit.
3. **Generation Flow** – validate clean workspace → craft prompt → call model → write file → auto‑`/context add`.
4. **Staleness Detection** – compare `repo-head` to `git rev-parse HEAD` on chat start; show banner if stale.
5. **Monorepo Support** – merge nearest parent/child `Q_CONTEXT.md` files.
6. **Secrets Hygiene** – skip or redact secrets (`*.env`, AWS keys) heuristically.
7. **Telemetry (opt‑in)** – record generation duration & file size for future optimisation.

## Non‑Functional Requirements

| Aspect | Target |
| ------------- | ----------------------------------------- |
| Performance | ≤ 2 min for 500 MB repo |
| Reliability | Roll back file if write fails |
| Security | No external calls except model invocation |
| Usability | File is plain Markdown; user‑editable |
| Compatibility | macOS & Linux now; Windows when supported |

## Error Handling & UX

| Scenario | Behaviour |
| -------------------- | -------------------------------------------------------- |
| Not a git repo | Ask whether to continue with plain scan |
| File exists | Prompt overwrite/append/cancel unless flag provided |
| Token limit exceeded | Abort with guidance to exclude paths or prune |
| Model quota error | Retry three times with back‑off, then show clear message |
| Permission denied | Print path & exit code 13 |

## Extensibility Hooks

* Run any scripts in `~/.q/init.d/*.sh` **after** file creation (e.g., run `prettier`).
* Plugin registry `~/.q/plugins/.ts` can inject extra sections.

## Testing Strategy

| Layer | Tests |
| ----------- | -------------------------------------------------- |
| Unit | `.gitignore` parser, YAML header serializer |
| Integration | End‑to‑end on sample Node, Java, Python repos |
| Regression | Verify staleness banner triggers when HEAD changes |
| Performance | Measure runtime versus repo size in CI |

## Documentation Updates

* Update `q chat --help` to include `/init`.
* New guide: *Bootstrapping Project Context with `/init`* (include GIF).
* Distinguish **shell** `q init` vs **chat** `/init` in docs and tab completion.

---

**Impact**: Empowers Amazon Q CLI with a first‑class “brain bootstrapper,” aligning it with competing developer AI tools and accelerating onboarding and productivity.