git:20260603.f6f909e to git:20260605.76e40dc

4 added, 12 removed. Audit A to A.

---

name: pin-query

description: Use when looking up pins by type, tags, or source. Drives lib/pins/query.ts to retrieve matching pin entries from the knowledge graph. Supersedes the legacy manual ls+frontmatter procedure.

---

# pin-query

Retrieve pins from the knowledge graph by calling `query(pinsDir, criteria)` from `lib/pins/query.ts`.

## Retrieval model

`query` calls `buildIndex()` on every invocation, scanning `pinsDir` in-memory. There is no `index.json` cache; every call performs a full directory scan and produces results directly.

The full entity set is always covered, including pins with no outgoing relations. Orphan pins remain findable by `type`, `tags`, or `source` — relation traversal is not required.

## Invocation

- Resolve `pinsDir` from the manifest before calling `query`:

- ```ts

- import { resolveManifest } from "lib/pins/manifest.ts";

- import { query } from "lib/pins/query.ts";

- const result = await resolveManifest();

- if (result.kind === 'absent') { /* handle missing manifest */ }

- const pinsDir = result.manifest.location;

+ Run the bundled script from the deployed skill directory:

- const results = query(pinsDir, { type: 'code', tags: ['auth'] });

- // returns QueryResult[] — each: { id: string, frontmatter: Frontmatter }

+ ```bash

+ bun "${CLAUDE_SKILL_DIR}/scripts/query.ts" [--type <type>] [--tags <tag1,tag2>] [--source <source>]

```

- `pinsDir` is `manifest.location` as resolved by `resolveManifest()` (from `lib/pins/manifest.ts`). Omit any criterion to leave that field unrestricted.

+ `--tags` accepts a comma-separated list; all tags must match (AND semantics). Omit any flag to leave that field unrestricted. The script resolves the manifest automatically — if no manifest exists it prints the absent message and exits 0.

## Presenting results

Return matched slugs (`id`), `source_url` from the frontmatter, and a one-line summary to the caller. Report "no match" on an empty result set. Do not re-traverse the graph; the returned `Frontmatter` already carries `relations` if the caller needs to follow links.