feat(cli): extract Obelisk runtime into npm package

Add @obelisk-apps/cli with the existing build, search, query, and attune contract plus official skill installation.

Separate the docs-only skill artifact, bootstrap installer, release layout, cross-platform CI, and package-level regression coverage.

skill-doc/references/pitfalls.md

@@ -0,0 +1,84 @@
+# Obelisk Pitfalls
+
+Use this after a query error, suspicious empty result, over-large output, or
+unclear helper row shape. For query design, read `retrieval-semantics.md` first.
+
+## Missing Columns And Wrong Aliases
+
+Common wrong guesses:
+
+- Summaries: use `source` and `content`; do not use `summary_type` or `text`.
+- Tool call name: use `tool_calls.name`. `tool_name` is only an alias in `SELECT tc.name AS tool_name`; `tc.tool_name` is not a column.
+- Tool call timestamps: `tool_calls` has no timestamp. Join `messages m ON m.uuid = tc.message_uuid`.
+- Tool result timestamps: `tool_results` has no timestamp. Join `messages m ON m.uuid = tr.message_uuid`.
+- Workflow agent message counts: `workflowTree()` returns `messageCount` for agents.
+
+When uncertain, inspect a tiny sample instead of guessing:
+
+```js
+const rows = summaries({ limit: 1 });
+return rows.length ? Object.keys(rows[0]) : [];
+```
+
+## FTS5 Syntax Errors
+
+`search(text)` uses raw FTS5 `MATCH`. Hyphenated terms and punctuation can be
+parsed as syntax.
+
+```js
+// tokenized phrase for FTS
+search('"workflow script"', { limit: 10 })
+```
+
+For literal punctuation, use SQL `LIKE` under the same scope:
+
+```js
+sql(`
+  SELECT m.uuid, s.id AS session_id, s.title, substr(m.text,1,180) AS snippet
+  FROM messages m
+  JOIN sessions s ON s.id = m.session_id
+  WHERE s.project LIKE ?
+    AND m.text LIKE ?
+  ORDER BY m.timestamp DESC
+  LIMIT 10
+`, '%quiet-zero%', '%workflow-script%')
+```
+
+## Over-Large Runtime JSON
+
+If runtime stdout is large, fix the query instead of reading it in chunks.
+
+- Lower `LIMIT`.
+- Shorten snippets to 160-240 chars.
+- Group in SQL/JS and return counts plus sparse examples.
+- For `fileHistory()`, filter to `Edit`/`Write` before projecting evidence.
+- For `workflowTree()`, omit `script`, `result_json`, and full agent messages unless explicitly requested.
+- Use `raw(uuid, { offset, limit })` only after identifying one specific message UUID.
+
+## Empty Results
+
+An empty array can be the correct answer for exact scopes or sentinels.
+
+When the user asks for a scoped project/file/session or exact term:
+
+1. run the scoped query;
+2. return `[]` or compact counts;
+3. say no matching prior result was found;
+4. do not call `recent()`, all-project `summaries()`, or `thread()` as fallback unless the user asks.
+
+## Counting From Snippets
+
+If the user asks "how many", "counts", "top N", or "group by", compute it in
+SQL or in the query script. Do not infer counts from visible snippets.
+
+```js
+sql(`
+  SELECT tc.name AS tool_name, COUNT(*) AS n
+  FROM tool_results tr
+  JOIN tool_calls tc ON tc.id = tr.tool_use_id
+  WHERE tr.is_error = 1
+  GROUP BY tc.name
+  ORDER BY n DESC
+  LIMIT 10
+`)
+```