pin-setup git:20260603.f6f909eA

Immutable. This exact content is served forever at /api/v1/blob/ee3fa280ef6d291c.

---
name: pin-setup
description: Use when initializing the pins knowledge graph for the first time in a project. Guides the user through creating pins.yaml (the storage manifest). Triggers on "setup pins", "initialize pins", "create pins.yaml", "first-run pins".
---

# pin-setup

First-run interview to create `pins.yaml`, the storage manifest for the pins knowledge graph.

## What is pins.yaml

`pins.yaml` is the manifest that tells the pins API where to read and write pin files. It declares the storage location and scope for this project's knowledge graph.

`resolveManifest()` (from `lib/pins/manifest.ts`) reads `pins.yaml` and returns the parsed manifest. Callers then extract `manifest.location` and pass it explicitly to each API (`record`, `query`, `audit`, etc.). The manifest itself is advisory metadata — individual API calls always receive `location` as an explicit argument, not by re-reading the file.

## Interview

Walk the user through three decisions:

### 1. Storage location

Ask: "Where should pin files live?"

Common choices:
- `~/.omt/<project>/pins/` — stored in the user's home directory, outside any repo
- `.pins/` inside the repo — stored alongside the project source
- A custom absolute path — for monorepos or multi-project setups

Confirm whether the directory should be created if it does not exist (it will be, automatically, on the first `record()` call).

### 2. Scope

Ask: "What is the scope of this pins manifest — personal (private) or project-wide (shared)?"

- `private` — pins default to `sensitivity: private`; not intended for team consumption
- `shared` — pins default to `sensitivity: shared`; meant to be read by teammates

The scope sets the manifest-level default; individual pins can override `sensitivity` in their frontmatter.

### 3. Git management

Ask: "Is this pins corpus managed under git?"

This is independent of storage location: a `~/.omt/...` directory can be a git repo; a `.pins/` directory inside a project repo can be gitignored. The answer reflects intent, not directory placement. When `git: true`, the SessionStart hook and the `pin-record`/`pin-wrap-up` skills will prompt the AI to commit pin file changes after recording.

Record the answer as `git: true` or `git: false`.

## Output

Once all three questions are answered, write `pins.yaml` at the project root (or the location the user specifies):

```yaml
# pins.yaml — knowledge graph storage manifest
location: <resolved absolute path>
scope: <private|shared>
git: <true|false>
```

Confirm the path is correct and the user understands that all pins API calls will resolve against this manifest.

## Migration

If the project has legacy pin files (frontmatter with `slug` instead of `id`, no `type` field), run migration after setup:

```ts
import { migrate } from 'lib/pins/migrate.ts';

await migrate({ location });
```

`migrate()` is idempotent — re-running it is safe. Each legacy file gets a `.bak` sibling before conversion.