@geoqiao/pi-ask 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,194 @@
+# [1.1.0](https://github.com/eko24ive/pi-ask/compare/v1.0.2...v1.1.0) (2026-06-22)
+
+
+### Bug Fixes
+
+* refresh pi dependency compatibility ([d6db94a](https://github.com/eko24ive/pi-ask/commit/d6db94a39d37fda632d53147592af8f53aa50e4b))
+
+
+### Features
+
+* add remote ask event contract ([69e8bab](https://github.com/eko24ive/pi-ask/commit/69e8bab6efbc0394aecb9ce416eea27da755a5df)), closes [#6](https://github.com/eko24ive/pi-ask/issues/6)
+
+## [1.0.2](https://github.com/eko24ive/pi-ask/compare/v1.0.1...v1.0.2) (2026-05-31)
+
+
+### Bug Fixes
+
+* avoid destructive ask config writes ([fa89c15](https://github.com/eko24ive/pi-ask/commit/fa89c1551a509690dee767165124450aac322c58))
+
+## [1.0.1](https://github.com/eko24ive/pi-ask/compare/v1.0.0...v1.0.1) (2026-05-22)
+
+
+### Bug Fixes
+
+* avoid config docs supply-chain false positive ([5d12c2f](https://github.com/eko24ive/pi-ask/commit/5d12c2fb8da82ca538999be65f58595c8aa54dde))
+* clarify ask_user prompt guidelines ([4afbe62](https://github.com/eko24ive/pi-ask/commit/4afbe62a42c80b13b8c77112a25cc68ab18ea3fa))
+
+# [1.0.0](https://github.com/eko24ive/pi-ask/compare/v0.9.0...v1.0.0) (2026-05-22)
+
+
+* feat!: migrate to latest pi packages ([a987406](https://github.com/eko24ive/pi-ask/commit/a9874062a50d4073a5379667620e1f2e457148a2))
+
+
+### BREAKING CHANGES
+
+* pi dependencies moved from @mariozechner/* to @earendil-works/*.
+
+Consumers must use the latest pi package scope.
+
+# [0.9.0](https://github.com/eko24ive/pi-ask/compare/v0.8.1...v0.9.0) (2026-05-06)
+
+
+### Bug Fixes
+
+* remove footer navigation hints ([45d8302](https://github.com/eko24ive/pi-ask/commit/45d8302e0a2e1527f0129bbb53fec38927a722ac))
+
+
+### Features
+
+* add ask notifications ([43cee4c](https://github.com/eko24ive/pi-ask/commit/43cee4c0f0cbbaf9673b67ca300ff5b05117819c))
+* add context-aware ask keymaps ([808b62c](https://github.com/eko24ive/pi-ask/commit/808b62cc77ee23093f2f672679ada1c34ec1a978))
+* add guarded config reset ([b218b8b](https://github.com/eko24ive/pi-ask/commit/b218b8b1889b163e5bd21fcb5083250921404a02))
+* add question type presentation controls ([f1a0a5d](https://github.com/eko24ive/pi-ask/commit/f1a0a5d5e5eb3591b90200921e88660517830dec))
+
+## [0.8.1](https://github.com/eko24ive/pi-ask/compare/v0.8.0...v0.8.1) (2026-05-03)
+
+
+### Bug Fixes
+
+* multi-select custom answer toggling ([780aac2](https://github.com/eko24ive/pi-ask/commit/780aac24cf58e144a8ab3ba6a29a75cf6fbf2656))
+* refine ask tool context typing ([cbabd44](https://github.com/eko24ive/pi-ask/commit/cbabd44acc0fadd4959602e8aa73c1c106856aad))
+
+# [0.8.0](https://github.com/eko24ive/pi-ask/compare/v0.7.0...v0.8.0) (2026-05-02)
+
+
+### Bug Fixes
+
+* rename settings modal title ([4feeec9](https://github.com/eko24ive/pi-ask/commit/4feeec9f0f535b4a129c8ce5d0f310f1365c6010))
+
+
+### Features
+
+* add answer extraction replay commands ([5b70eca](https://github.com/eko24ive/pi-ask/commit/5b70eca306e15335e0a24754280c1ea6d9787bbf))
+* **config:** add migration framework ([288caf4](https://github.com/eko24ive/pi-ask/commit/288caf49de4a78e35845187f736b9685f732c5cc))
+
+# [0.7.0](https://github.com/eko24ive/pi-ask/compare/v0.6.1...v0.7.0) (2026-04-29)
+
+
+### Bug Fixes
+
+* **package:** declare bundled skills in pi manifest ([3c26bfa](https://github.com/eko24ive/pi-ask/commit/3c26bfa7c995fd4fb22d391db784ceaf76594e4c))
+* pass custom answers through elaborate output ([85962d9](https://github.com/eko24ive/pi-ask/commit/85962d985d7a8064093f8643f4706d8d98888050))
+
+
+### Features
+
+* add ask settings modal shell ([5c0d896](https://github.com/eko24ive/pi-ask/commit/5c0d8964fba099e85472c42ab442bd5b86480de1))
+* add config-backed ask keymaps ([e8a36b7](https://github.com/eko24ive/pi-ask/commit/e8a36b72eff4f43f8d3944846dbe58bb605210a9))
+* add dirty-dismiss and footer hint settings ([18120e8](https://github.com/eko24ive/pi-ask/commit/18120e880119cff23e2fdc2cf49cdf3fbb512829))
+* add review shortcut confirmation setting ([67891d1](https://github.com/eko24ive/pi-ask/commit/67891d147f4bde4bb84edc1e8eca4d91786c1056))
+* bootstrap ask config on first use ([2bf85b3](https://github.com/eko24ive/pi-ask/commit/2bf85b3f6f19a71972df8b989ccc6670397c4e38))
+* **ui:** add ask keymap help modal ([c9930b4](https://github.com/eko24ive/pi-ask/commit/c9930b494f89320498db9b9828415f331605c3ff))
+
+## [0.6.1](https://github.com/eko24ive/pi-ask/compare/v0.6.0...v0.6.1) (2026-04-27)
+
+
+### Bug Fixes
+
+* remove automatic lefthook install ([4f1c598](https://github.com/eko24ive/pi-ask/commit/4f1c59818137cbcd335d5153c835e3f420aab575))
+
+# [0.6.0](https://github.com/eko24ive/pi-ask/compare/v0.5.1...v0.6.0) (2026-04-25)
+
+
+### Bug Fixes
+
+* **ui:** tighten ask layout rendering ([3515098](https://github.com/eko24ive/pi-ask/commit/351509838cd14ad251ca4b152c0bb4577c9d7b79))
+
+
+### Features
+
+* **ui:** improve narrow-screen tab and footer rendering ([1ce7210](https://github.com/eko24ive/pi-ask/commit/1ce721094c21faf6180098a7244b6f2abd13623e))
+* **ui:** split submit tab into actions and review ([b59c967](https://github.com/eko24ive/pi-ask/commit/b59c967d985a6f62dc32da3b4f2c5767d01608a9))
+* **ui:** support custom answers in preview questions ([7cca5eb](https://github.com/eko24ive/pi-ask/commit/7cca5eb54d1964d19ce17ebb45507f1939960b8b))
+
+## [0.5.1](https://github.com/eko24ive/pi-ask/compare/v0.5.0...v0.5.1) (2026-04-25)
+
+
+### Bug Fixes
+
+* **skills:** align bundled skill name with folder ([005151f](https://github.com/eko24ive/pi-ask/commit/005151f79ba562c08e0fe9b5bccf59e964c02a32))
+
+# [0.5.0](https://github.com/eko24ive/pi-ask/compare/v0.4.0...v0.5.0) (2026-04-24)
+
+
+### Features
+
+* add submit screen number hotkeys ([c10c61f](https://github.com/eko24ive/pi-ask/commit/c10c61f1ebb061dab1daf7404089ce6b57c8917c))
+* **skill:** add ask-user decision gate profile ([6d9cb5b](https://github.com/eko24ive/pi-ask/commit/6d9cb5b7bfde54c7522f8e8321046161af296dad))
+
+# [0.4.0](https://github.com/eko24ive/pi-ask/compare/v0.3.0...v0.4.0) (2026-04-24)
+
+
+### Features
+
+* improve ask flow elaboration and validation ([b7c7301](https://github.com/eko24ive/pi-ask/commit/b7c7301f974c81eb82070810304a9267f62d7699))
+
+# [0.3.0](https://github.com/eko24ive/pi-ask/compare/v0.2.0...v0.3.0) (2026-04-23)
+
+
+### Bug Fixes
+
+* allow empty editor navigation shortcuts ([5d7ccc8](https://github.com/eko24ive/pi-ask/commit/5d7ccc8ce2e45c70a36932f048a90419dcb59304))
+
+
+### Features
+
+* harden ask tool validation and fallback ([050e880](https://github.com/eko24ive/pi-ask/commit/050e8800cdcd97be635bb95d9500a309d207f7f8))
+
+# [0.2.0](https://github.com/eko24ive/pi-ask/compare/v0.1.1...v0.2.0) (2026-04-19)
+
+
+### Bug Fixes
+
+* improve custom input editor rendering ([bc92712](https://github.com/eko24ive/pi-ask/commit/bc9271205335bb9e610f8cd0c6e86bea5ce22f4b))
+* keep arrow keys and tab inside editor mode ([cdea90b](https://github.com/eko24ive/pi-ask/commit/cdea90bbfe726f4edca131513cf96e81a5307782))
+* polish ask note spacing and styling ([e0e2b04](https://github.com/eko24ive/pi-ask/commit/e0e2b046883b9d07745a6178c49cfef25e771424))
+* preserve multi-select choices with custom answers ([8d8e7b6](https://github.com/eko24ive/pi-ask/commit/8d8e7b67c97e796de0e44b8935960a8d39b55360))
+
+
+### Features
+
+* refine ask submit screen layout ([d5ca38e](https://github.com/eko24ive/pi-ask/commit/d5ca38e621f701af466a9b67005708ebd176bbf0))
+* sharpen ask_user tool guidance ([4a131f7](https://github.com/eko24ive/pi-ask/commit/4a131f7752f17f2f91fd6669e45a74888240d86e))
+* simplify ask UI copy and note shortcuts ([9ab368a](https://github.com/eko24ive/pi-ask/commit/9ab368ad6bebdf26d8a4be7de71ac415eea06285))
+* support @ file autocomplete in ask editor ([0386239](https://github.com/eko24ive/pi-ask/commit/0386239f5e4165281b40db540d129d86c8af63d4))
+* support ctrl+c dismissal in ask flow ([fcd1f1b](https://github.com/eko24ive/pi-ask/commit/fcd1f1bce5120af07c7d6499591295e4bccf6a55))
+
+## [0.1.1](https://github.com/eko24ive/pi-ask/compare/v0.1.0...v0.1.1) (2026-04-19)
+
+
+### Bug Fixes
+
+* relax toolchain pinning for release workflow ([549c2c2](https://github.com/eko24ive/pi-ask/commit/549c2c26f04f5c2d6b7b3f6487a7a72303f998bb))
+* remove toolchain pinning from repo ([5b10568](https://github.com/eko24ive/pi-ask/commit/5b105683c35dc02df1e1e0fc6132a46283c25d1b))
+* specify pnpm version in workflows ([08e053f](https://github.com/eko24ive/pi-ask/commit/08e053f095ed5ccc68a367f03c07a30b31683b3c))
+
+# [0.1.0](https://github.com/eko24ive/pi-ask/compare/v0.0.0...v0.1.0) (2026-04-19)
+
+
+### Bug Fixes
+
+* skip git hooks during release commits ([32c2ae7](https://github.com/eko24ive/pi-ask/commit/32c2ae785c16ab2482f9f2a09d19c8eeed8cae8e))
+* update release tooling for trusted publishing ([85f4ec5](https://github.com/eko24ive/pi-ask/commit/85f4ec5128ba4554412e3409d9f353fb66981f35))
+
+
+### Features
+
+* bootstrap first public release ([552959f](https://github.com/eko24ive/pi-ask/commit/552959f7ad3b40a9f3f8443d301a2c6f2340477d))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is driven by semantic-release.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 eko24ive
+Copyright (c) 2026 geoqiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+![pi-ask main image](docs/media/pi-ask-main.png)
+
+# @geoqiao/pi-ask
+
+[![npm downloads](https://badgen.net/npm/dm/@geoqiao/pi-ask)](https://www.npmjs.com/package/@geoqiao/pi-ask)
+[![last commit](https://badgen.net/github/last-commit/geoqiao/pi-ask)](https://github.com/geoqiao/pi-ask/commits/main)
+[![stars](https://badgen.net/github/stars/geoqiao/pi-ask)](https://github.com/geoqiao/pi-ask/stargazers)
+
+`@geoqiao/pi-ask` is an independently maintained continuation of [`eko24ive/pi-ask`](https://github.com/eko24ive/pi-ask). It is an ask tool that cares about your answers.
+
+It lets an agent pause, ask structured questions in a terminal UI, and continue with normalized answers instead of guessing.
+
+![pi-ask demo](docs/media/pi-ask-demo.gif)
+
+High-quality video: [demo.mp4](https://github.com/user-attachments/assets/a8503ca9-afcb-4c31-9edc-353b985a0209)
+
+## Install
+
+```bash
+pi install npm:@geoqiao/pi-ask
+```
+
+You can also install from git:
+
+```bash
+pi install git:github.com/geoqiao/pi-ask
+```
+
+Or try it without installing (load once for the current run):
+
+```bash
+pi -e npm:@geoqiao/pi-ask
+```
+
+## Features
+
+Once installed, this package gives the agent a native way to ask for clarification instead of guessing.
+
+- 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
+- ✍️ Inline free-form `Type your own` answers
+- 📎 Native pi-style `@` file references inside answer and note editors
+- 📝 Question-level and option-level notes
+- 👀 Review tab with `Submit`, `Elaborate`, and `Cancel`
+- 💬 Elaboration flow to capture note-based clarification before final submission
+- ⌨️ Context-aware customizable keymaps with aliases for main flow, editors, and settings
+- ⚙️ Ask settings with persisted behaviour, notifications, keymaps, and `/answer` extraction config
+- 🔔 Optional external notifications when an ask flow is waiting for input
+- 🔁 Slash commands for fallback/replay:
+  - `/answer` extracts questions from the latest assistant message into an ask flow
+  - `/answer:again` reopens the latest `/answer` form on the current branch
+  - `/ask:replay` replays the latest real `ask_user` form on the current branch
+- 🗣️ You can talk to your agent to configure pi-ask; it will read the bundled configuration guide and tailor the config for you
+
+## Feature walkthrough
+
+### Native `@` file references
+Use pi-style `@` file path autocomplete inside free-form answers and note editors.
+
+![Native pi-style @ file references inside the ask flow](docs/media/feature-at-file-mentions.png)
+
+### Option and question notes
+Attach clarification notes to a specific option (`n`) or add broader question-level context (`Shift+N`).
+
+| Option notes | Question notes |
+|---|---|
+| ![Option note editor with note text for selected option](docs/media/feature-option-note.png) | ![Question-level note editor with saved note](docs/media/feature-question-note.png) |
+
+### Review tab — Elaborate and Submit
+Ask the agent to elaborate on notes before finalizing choices, or review all answers before returning them to the agent.
+
+| Elaborate | Submit |
+|---|---|
+| ![Review tab with Elaborate action and expanded note preview](docs/media/feature-review-elaborate.png) | ![Review tab with Submit action highlighted](docs/media/feature-review-submit.png) |
+
+### Single-select and multi-select questions
+Pick one option when answers are mutually exclusive, or choose multiple options when several answers apply.
+
+| Single-select | Multi-select |
+|---|---|
+| ![Single-select question with one selected option](docs/media/feature-single-select.png) | ![Multi-select question with multiple selected options](docs/media/feature-multi-select.png) |
+
+### Preview mode
+Use a dedicated preview pane when options need richer detail.
+
+![Preview question showing a dedicated preview pane](docs/media/feature-preview-pane.png)
+
+### Custom answer (`Type your own`)
+Capture free-form input inline without leaving the flow.
+
+![Inline custom answer input for Type your own option](docs/media/feature-custom-answer-input.png)
+
+## Default key bindings
+
+Open ask settings with `?` during the ask flow, or with the `/ask-settings` command from pi.
+
+Keymaps are context-aware and configurable in `~/.pi/agent/extensions/eko24ive-pi-ask.json`.
+Each action accepts a key string or an array of aliases.
+
+Default contexts:
+
+- `global`: `dismiss` (`Ctrl+C`) and `settings` (`?`)
+- `main`: confirm/cancel/toggle, tab navigation, option navigation, and note shortcuts
+- `editor`: custom answer submit/close and empty-editor navigation
+- `noteEditor`: note save/close and empty-editor navigation
+- `settingsModal`: close, next/previous setting, and toggle
+
+Fixed bindings:
+
+| Key | Context | Effect |
+|---|---|---|
+| `1..9` | Options list | Select or toggle matching option |
+| `1` `2` `3` | Review tab | Trigger `Submit` / `Elaborate` / `Cancel` |
+| `@` | Editors | File-reference affordance |
+| Arrow keys / `Tab` | Non-empty editor | Stay in editor for cursor movement |
+
+Review-tab shortcuts can optionally require the same number key twice via `behaviour.doublePressReviewShortcuts`. `behaviour.presentSingleAsMulti` can render future single-select questions as multi-select while preserving the requested type in results; use `main.changeQuestionType` (`t` by default) to change the active question type live.
+
+You can edit the config file yourself, ask pi to edit it for you, or use `/ask-settings` to find the exact config path, toggle behaviour/notification settings, or reset config to defaults with a guarded double press. pi-ask treats the config file as user-owned: load-time migrations and invalid files are handled in memory without rewriting or backing up the file, and read-only/externally managed configs fail gracefully with a manual-edit message.
+
+```json
+{
+  "schemaVersion": 5,
+  "answer": {
+    "extractionModels": [
+      { "provider": "openai-codex", "id": "gpt-5.4-mini" },
+      { "provider": "github-copilot", "id": "gpt-5.4-mini" },
+      { "provider": "anthropic", "id": "claude-haiku-4-5" }
+    ],
+    "extractionTimeoutMs": 30000,
+    "extractionRetries": 1
+  },
+  "behaviour": {
+    "autoSubmitWhenAnsweredWithoutNotes": false,
+    "confirmDismissWhenDirty": true,
+    "doublePressReviewShortcuts": true,
+    "presentSingleAsMulti": false,
+    "showFooterHints": true
+  },
+  "keymaps": {
+    "global": { "dismiss": ["ctrl+c"], "settings": ["?"] },
+    "main": {
+      "confirm": ["enter"],
+      "cancel": ["esc"],
+      "toggle": ["space"],
+      "changeQuestionType": ["t"],
+      "nextTab": ["tab", "right"],
+      "previousTab": ["shift+tab", "left"],
+      "nextOption": ["down"],
+      "previousOption": ["up"],
+      "optionNote": ["n"],
+      "questionNote": ["shift+n"]
+    },
+    "editor": {
+      "submit": ["enter"],
+      "close": ["esc"],
+      "nextTabWhenEmpty": ["tab", "right"],
+      "previousTabWhenEmpty": ["shift+tab", "left"],
+      "nextOptionWhenEmpty": ["down"],
+      "previousOptionWhenEmpty": ["up"]
+    },
+    "noteEditor": {
+      "save": ["enter"],
+      "close": ["esc"],
+      "nextTabWhenEmpty": ["tab", "right"],
+      "previousTabWhenEmpty": ["shift+tab", "left"],
+      "nextOptionWhenEmpty": ["down"],
+      "previousOptionWhenEmpty": ["up"]
+    },
+    "settingsModal": {
+      "close": ["esc", "ctrl+c", "?"],
+      "nextOption": ["down"],
+      "previousOption": ["up"],
+      "toggle": ["enter", "space"]
+    }
+  },
+  "notifications": {
+    "enabled": true,
+    "channels": ["bell"]
+  }
+}
+```
+
+Accepted notation follows pi-tui key ids. Common aliases are normalized, for example `escape` → `esc`, `return` → `enter`, `control+c` → `ctrl+c`, and `Shift+N` → `shift+n`.
+
+## Use
+
+After installation, the extension registers the `ask_user` tool plus `/ask-settings`, `/answer`, `/answer:again`, and `/ask:replay` commands.
+
+Agents can auto-discover and call `ask_user` when they need clarification instead of guessing. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
+
+### Answer and replay commands
+
+`/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It extracts questions from the latest completed assistant message and opens the same ask UI.
+
+Replay commands are branch-aware. They read persisted entries from the current pi session branch, so they work naturally with `/resume`, `/tree`, and conversation branching:
+
+- `/answer:again` reopens the latest form created by `/answer` on this branch
+- `/ask:replay` reopens the latest real `ask_user` form on this branch
+
+Cancellation is local to the UI: closing a replayed form does not start a new agent turn. Submitted answers are sent back as a normal user follow-up message.
+
+Kudos to [@k0valik](https://github.com/k0valik) for the `/answer` idea.
+
+You can also talk to pi to configure this extension. When asked to customize pi-ask settings, keymaps, notifications, or extraction behavior, the agent is instructed to read the bundled `docs/configuration.md` guide first and then edit the config file accordingly.
+
+This package also bundles the `ask-user` skill profile from `skills/ask-user/SKILL.md`. It reinforces when to use the tool, is enabled by default when installed, and can be disabled via `pi config`. The skill was inspired by https://github.com/edlsh/pi-ask-user.
+
+You can still add your own agent instruction if you want to further reinforce usage.
+
+For exact input/output and UX guarantees, see [`docs/contract.md`](docs/contract.md).
+
+## Local development
+
+### Run locally in pi
+
+```bash
+pi -e ./src/index.ts
+```
+
+### Run in isolated test mode (extension + bundled skill only)
+
+```bash
+pnpm dev
+pnpm dev ../test
+```
+
+`pnpm dev [path]` runs pi with `--no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files`, loads this repo’s extension and `skills/ask-user`, and starts pi from `[path]` by changing directories before launch (defaults to `.`).
+
+### Install dependencies
+
+```bash
+pnpm install
+```
+
+### Install git hooks (contributors)
+
+`lefthook` is not installed automatically. If you want the local commit hooks used by this repo, run:
+
+```bash
+pnpm exec lefthook install
+```
+
+### Development commands
+
+```bash
+pnpm format
+pnpm lint
+pnpm check
+pnpm typecheck
+pnpm test
+```
+
+### Commit workflow
+
+This repo uses `lefthook`, Commitizen, conventional commitlint, and semantic-release.
+
+If you want local hooks, install them once after `pnpm install`:
+
+```bash
+pnpm exec lefthook install
+```
+
+Recommended flow:
+
+```bash
+pnpm commit
+```
+
+## Project layout
+
+- `src/` — TypeScript extension implementation
+- `tests/` — behavior-focused tests
+- `docs/` — small docs set for contract and architecture
+- `docs/media/` — repository-only README media assets
+
+## Documentation
+
+Docs stay intentionally small:
+
+- `docs/README.md` — index
+- `docs/contract.md` — external behavior
+- `docs/architecture.md` — module boundaries and invariants

package/docs/README.md

@@ -0,0 +1,33 @@
+# Docs
+
+This folder keeps only the documentation needed to understand and maintain the extension without turning docs into a second copy of the code.
+
+## Files
+
+- `configuration.md` — source of truth for configuring pi-ask keymaps, behaviour, and `/answer` extraction
+- `contract.md` — external behavior, tool payload/result details, and UX guarantees
+- `remote-events.md` — local inter-extension event contract, bridge examples, and smoke-test steps
+- `architecture.md` — module boundaries and invariants
+- `../skills/ask-user/SKILL.md` — auto-bundled agent-side decision-gate guidance; enabled by default, but can be disabled via `pi config`; inspired by https://github.com/edlsh/pi-ask-user
+
+## Reading order
+
+- start with `configuration.md` for config-editing rules
+- read `contract.md` for behavior
+- read `remote-events.md` for local bridge/event integration
+- read `architecture.md` for code layout
+
+## Local test run
+
+From repo root, run:
+
+```bash
+pnpm dev
+pnpm dev ../some-target-folder
+```
+
+This starts pi in isolated mode, loads only this extension and bundled `ask-user` skill, and uses the optional folder as `--cd` target.
+
+## Rule of thumb
+
+If a detail is about implementation mechanics, it should usually live in `src/` or `tests/`, not here.