git:20260602.aa94fab to git:20260602.39fde20

12 added, 3 removed. Audit A to A.

---

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. All lib/pins APIs (`record`, `migrate`, `query`, etc.) resolve their `location` parameter from this manifest.

## Interview

- Walk the user through two decisions:

+ Walk the user through three decisions:

### 1. Storage location

Ask: "Where should pin files live?"

Common choices:

- - `~/.omt/<project>/pins/` — user-local, not checked into the repo (default for private or personal knowledge)

- - `.pins/` inside the repo — team-shared, checked in (good for project-wide shared knowledge)

+ - `~/.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 both 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.