# `detect`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Reports what is already present at the target skills directory. The host
calls `detect(ctx)` before prompts run; the result feeds into the user's
decision about whether to proceed, `--force`, or supply `--only` /
`--exclude` to limit the install. Detect is read-only: it only inspects
`ctx.fs` and never mutates state.

## Features

- Reports `alreadyInstalled: boolean` based on the target directory's
  presence — `false` means a fresh install path.
- Lists existing skill directories as `conflicts` (excluding
  `index.json`) so the host UI can show what would be touched.
- Defaults to scanning `.suaveplan/skills` relative to `ctx.cwd`; the
  optional second argument lets callers pre-supply a target dir from
  partial answers.
- Tolerant of degenerate states — when `listDir` throws (e.g. the target
  is a file masquerading as a dir), returns `conflicts: []` rather than
  propagating the error.

## Basic Example

```ts
import { detect } from "@suaveplan/install-agent-skills";

const result = await detect(ctx);
if (result.alreadyInstalled) {
    console.warn("Skills already installed; use --force to overwrite");
}
```

## Advanced Example

```ts
import { detect } from "@suaveplan/install-agent-skills";

const result = await detect(ctx, { targetDir: "/srv/agent/skills" });
if (result.alreadyInstalled && (result.conflicts?.length ?? 0) > 0) {
    console.log("Existing skills:");
    for (const id of result.conflicts ?? []) {
        console.log(`  - ${id}`);
    }
    console.log(
        `Run again with --only ${result.conflicts?.join(",")} to refresh just those`
    );
}
```

## API Reference

- `detect(ctx, answers?): Promise<DetectResult>` — `answers` may be
  partial; only `targetDir` is consulted at this stage.
- Return shape — `{ alreadyInstalled, conflicts?, notes? }` from the
  host's `DetectResult` type.

## Implementation Notes

Detect runs _before_ prompts so it can't access fully-validated answers;
the partial `answers` parameter lets the bin pass through whatever the
user already supplied (e.g. via `--answers <file>`). Reading the
target's directory listing instead of stating each known skill's
manifest is cheaper and gives the user a holistic view — including
unrelated skills that were dropped into the directory by hand.