@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Report a reproducible problem with pi-browser-harness
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+Describe the problem clearly. Include what browser action or pi tool failed, if applicable.
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+Please include the exact prompt, command, or tool call sequence when possible.
+
+## Expected Behavior
+
+What did you expect to happen?
+
+## Actual Behavior
+
+What happened instead? Include error messages, screenshots, or relevant logs if available.
+
+## Environment
+
+- OS:
+- Node version (`node --version`):
+- Chrome / Chromium / Edge version:
+- pi version:
+- pi-browser-harness version or commit:
+- Install method (`npm`, `git`, local path):
+
+## Additional Context
+
+Add any other context that may help diagnose the issue, such as whether Chrome remote debugging was enabled through `chrome://inspect/#remote-debugging` or launched with `--remote-debugging-port=9222`.

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an improvement or new browser-control capability
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem Statement
+
+What problem are you trying to solve? Describe the workflow, limitation, or browser-control gap.
+
+## Proposed Solution
+
+Describe the behavior you would like to see. If this is a new browser tool, include the proposed `browser_*` name, inputs, and expected output if you have a preference.
+
+## Alternatives Considered
+
+What alternatives or workarounds have you tried? For example, could this be handled with `browser_execute_js`, `browser_http_get`, or `browser_run_script` today?
+
+## Additional Context
+
+Add examples, screenshots, links, or related Chrome DevTools Protocol details that would help explain the request.

@@ -0,0 +1,29 @@
+## Description
+
+Describe what this PR changes and why. Include user-facing behavior changes, new browser tools, or documentation updates.
+
+## Related Issue
+
+Closes #
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactor or maintenance
+- [ ] Release or packaging change
+- [ ] Other:
+
+## Testing
+
+Describe how you tested the change. Include local pi install steps or browser workflows when relevant.
+
+## Checklist
+
+- [ ] I ran `npm run typecheck`.
+- [ ] I ran `npm pack --dry-run` or otherwise verified packaging when package contents changed.
+- [ ] I tested locally with `pi install /path/to/pi-browser-harness` when runtime behavior changed.
+- [ ] I updated README documentation for user-facing changes.
+- [ ] I updated CHANGELOG.md for user-facing changes.
+- [ ] I kept the change focused and avoided unrelated rewrites.

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck-and-pack:
+    name: Typecheck and package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Verify npm package
+        run: npm pack --dry-run

@@ -2,7 +2,7 @@ # Changelog
 
 All notable changes to pi-browser-harness will be documented in this file.
 
-## [0.1.0] - Unreleased
+## [0.1.0] - 2026-05-02
 
 ### Added
 - Initial release of pi-browser-harness.

@@ -0,0 +1,154 @@
+# Contributing to pi-browser-harness
+
+Thanks for your interest in improving `pi-browser-harness`. This project gives pi agents full browser control through the Chrome DevTools Protocol (CDP): navigation, screenshots, clicks, typing, JavaScript evaluation, tab management, and runtime helper scripts.
+
+---
+
+## Setup
+
+### 1. Fork and clone
+
+```bash
+git clone https://github.com/YOUR_USERNAME/pi-browser-harness.git
+cd pi-browser-harness
+```
+
+If you are working directly from the upstream repository:
+
+```bash
+git clone https://github.com/amankumarsingh77/pi-browser-harness.git
+cd pi-browser-harness
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+### 3. Run the local checks
+
+```bash
+npm run typecheck
+npm pack --dry-run
+```
+
+`npm run typecheck` validates the TypeScript source. `npm pack --dry-run` verifies that the package can be packed for publishing and shows which files will be included.
+
+---
+
+## Project structure
+
+```text
+.
+├── src/
+│   ├── index.ts       # Extension entry point and command registration
+│   ├── tools.ts       # Browser tool schemas, handlers, and result rendering hooks
+│   ├── daemon.ts      # Connection lifecycle for the browser-harness daemon
+│   ├── protocol.ts    # Types for browser/daemon protocol messages
+│   ├── setup.ts       # /browser-setup implementation and Chrome detection
+│   ├── state.ts       # Session state persistence
+│   ├── prompt.ts      # Browser usage guidance injected into the agent prompt
+│   └── renderers.ts   # TUI renderers for screenshots and tab listings
+├── skills/
+│   └── pi-browser-harness/
+│       └── SKILL.md   # Agent skill documentation
+├── README.md          # User-facing documentation
+├── CHANGELOG.md       # Release notes
+└── package.json       # npm package metadata and pi manifest
+```
+
+---
+
+## Developing locally
+
+Make changes in `src/`, then run:
+
+```bash
+npm run typecheck
+```
+
+To test the extension in pi from your local checkout, install it by path:
+
+```bash
+pi install /absolute/path/to/pi-browser-harness
+```
+
+For example:
+
+```bash
+pi install "$PWD"
+```
+
+Then start pi and run:
+
+```text
+/browser-setup
+/browser-status
+```
+
+Use the normal browser workflow when testing: screenshot → act → screenshot → verify. For example, navigate to a page, wait for load, capture a screenshot, and confirm the result visually.
+
+---
+
+## Code conventions
+
+- Write TypeScript and keep the project passing `npm run typecheck`.
+- Keep `strict` TypeScript mode clean. Do not introduce implicit `any` values.
+- Prefer small, focused changes over broad rewrites.
+- Keep tool descriptions, parameter descriptions, and prompt guidelines clear and user-facing.
+- Preserve the existing error-handling style: return useful, actionable messages to the agent instead of leaking low-level details when possible.
+- Avoid adding dependencies unless they are necessary for the browser-control experience.
+- Keep README and CHANGELOG updates in the same PR when behavior changes.
+
+---
+
+## Adding a new browser tool
+
+Most browser tools are registered in `src/tools.ts` through `pi.registerTool`.
+
+When adding a tool:
+
+1. Add or reuse the underlying daemon method in `src/daemon.ts` and protocol types in `src/protocol.ts` when needed.
+2. Register the pi tool in `src/tools.ts` with:
+   - a stable `browser_*` name,
+   - a concise label and description,
+   - a TypeBox parameter schema,
+   - prompt snippets and guidelines that explain when to use it,
+   - clear result text and structured details where useful.
+3. Update prompt guidance in `src/prompt.ts` if the tool changes recommended workflows.
+4. Add or update a renderer in `src/renderers.ts` if the tool returns visual or rich output.
+5. Document the tool in `README.md` and note the change in `CHANGELOG.md`.
+6. Run:
+
+   ```bash
+   npm run typecheck
+   npm pack --dry-run
+   ```
+
+Keep tool behavior predictable. The agent should be able to verify actions with screenshots or page state after every interaction.
+
+---
+
+## Pull request process
+
+1. Fork the repository.
+2. Create a focused branch:
+
+   ```bash
+   git checkout -b fix/short-description
+   ```
+
+3. Make your changes and keep commits readable.
+4. Run local checks:
+
+   ```bash
+   npm run typecheck
+   npm pack --dry-run
+   ```
+
+5. Test in pi with a local path install when the change affects runtime behavior.
+6. Update documentation and CHANGELOG entries when user-visible behavior changes.
+7. Open a pull request against `main` and describe what changed, how it was tested, and any follow-up work.
+
+Thank you for helping make browser automation in pi reliable, inspectable, and easy to use.

@@ -7,8 +7,11 @@
 ## Quick Start
 
 ```bash
-# 1. Install (from this repo, until published to npm)
-pi install git:github.com/amankumarsingh77/pi-browser-harness
+# 1. Install
+pi install npm:pi-browser-harness
+
+# Or install from GitHub:
+# pi install git:github.com/amankumarsingh77/pi-browser-harness
 
 # 2. Enable Chrome remote debugging
 #    Open chrome://inspect/#remote-debugging in Chrome,

@@ -28,6 +28,7 @@ },
   "files": [
     "src/",
     "skills/",
+    "assets/",
     "tsconfig.json",
     "LICENSE",
     "README.md",