LockInTime · yashranaway · Aug 5, 2026 · Aug 5, 2026
@@ -0,0 +1,21 @@
+# Code owners are requested for review automatically.
+# Order matters: the last matching pattern wins.
+
+*                                   @SarthakWade
+
+# Security-critical surfaces — the host-enforced contracts live here.
+/apps/headless/Sources/HeadlessProtocol/Protocol.swift      @SarthakWade
+/apps/headless/Sources/HeadlessProtocol/Transport.swift     @SarthakWade
+/apps/headless/Sources/HeadlessProtocol/Artifacts.swift     @SarthakWade
+/apps/headless/Sources/HeadlessProtocol/AgentRuntime.swift  @SarthakWade
+/apps/headless/LinuxHost/                                   @SarthakWade
+/apps/headless/Host/                                        @SarthakWade
+
+# Product direction. Changes here are decisions, not refactors.
+/docs/ROADMAP.md                    @SarthakWade
+/docs/roadmap/                      @SarthakWade
+/SECURITY.md                        @SarthakWade
+/AGENTS.md                          @SarthakWade
+
+# Release and CI plumbing.
+/.github/workflows/                 @SarthakWade
@@ -0,0 +1,66 @@
+name: Bug report
+description: Something in Headless behaves incorrectly
+labels: ["type:bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        If this is a **security** issue — a way past navigation rules, the
+        artifact store, the socket boundary, or redaction — do not file it
+        here. Use [private vulnerability reporting](https://github.com/LockInTime/headless/security/advisories/new).
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you expect, and what did you get instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Commands to reproduce
+      description: The exact `headless` commands, in order. Include the page or fixture if it matters.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: engine
+    attributes:
+      label: Engine
+      options:
+        - macOS (WKWebView)
+        - Linux (Chromium)
+        - Linux via Docker image
+        - Both / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `headless capabilities` (protocol version) plus the release tag or commit you built from.
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Output and diagnostics
+      description: |
+        The failing JSON response, and anything relevant from `headless qa report`,
+        `console list`, or `network list`. Redact page content you cannot share.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I checked the [improvements backlog](https://github.com/LockInTime/headless/blob/main/docs/roadmap/improvements-backlog.md) and open `backlog` issues for an existing entry
+          required: true
+        - label: This is not a documented limitation in the [phase contracts](https://github.com/LockInTime/headless/tree/main/apps/headless/docs) (P0/P1/P2)
+          required: true
@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/LockInTime/headless/security/advisories/new
+    about: Report privately. Never open a public issue for a boundary bypass.
+  - name: Roadmap and backlog
+    url: https://github.com/LockInTime/headless/blob/main/docs/ROADMAP.md
+    about: Planned work, phases, and the definition of done. Most known gaps are already filed as `backlog` issues.
+  - name: Using Headless as an agent tool
+    url: https://github.com/LockInTime/headless/blob/main/.agents/skills/headless-computer-use/SKILL.md
+    about: The skill that teaches an agent how to drive Headless safely.
@@ -0,0 +1,56 @@
+name: Feature or command proposal
+description: Propose a new capability, command, or parameter
+labels: ["type:feature", "status:needs-design"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Headless has deliberate non-goals. These will be closed:
+        an arbitrary-JavaScript verb, a TCP listener or remote control without
+        authentication, page-download support, and desktop/OS automation.
+        See [what is excellent](https://github.com/LockInTime/headless/blob/main/docs/roadmap/what-is-excellent.md).
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What can an agent not do today
+      description: Describe the task that fails or requires glue code, not the solution you have in mind.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed surface
+      description: The command or parameter as an agent would type it, and the response shape you expect.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: engines
+    attributes:
+      label: Which engines can support this
+      options:
+        - Both engines
+        - Chromium only (macOS returns UNSUPPORTED_CAPABILITY)
+        - WKWebView only (Linux returns UNSUPPORTED_CAPABILITY)
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: contracts
+    attributes:
+      label: Effect on the contracts
+      description: |
+        How does this interact with the host-enforced rules — bounded output,
+        untrusted content marking, fail-closed validation, no arbitrary
+        execution? If it needs an architecture-decision entry, say so.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
@@ -0,0 +1,48 @@
+<!--
+Thanks for contributing. Keep this template short and honest — delete
+sections that genuinely do not apply, rather than ticking boxes you did not
+verify.
+-->
+
+## What this changes
+
+<!-- One paragraph. What behaviour is different after this merges? -->
+
+Closes #
+
+## Why
+
+<!-- Link the backlog item (§A1, §B3, …) or the decision that motivates it. -->
+
+## How it was verified
+
+<!-- Name what you actually ran. "CI will tell us" is not verification. -->
+
+- [ ] `pnpm test`
+- [ ] `pnpm test:runtime`
+- [ ] `pnpm test:e2e:linux` — required if this touches a host, transport, agent runtime JS, or artifacts
+- [ ] `pnpm test:e2e:mac` — or the `macos-e2e` label, required if this touches `main.swift`, `Host/`, or capture code
+- [ ] New or updated tests cover the change
+
+## Contracts
+
+<!--
+These are host-enforced and must survive. Confirm the ones your change comes
+near; delete the rest. See docs/roadmap/what-is-excellent.md
+-->
+
+- [ ] No arbitrary-JS verb, no TCP listener, no debug port introduced
+- [ ] Navigation stays HTTP/HTTPS only; downloads stay denied
+- [ ] Artifacts stay bare-named, `O_EXCL`, `0600`, non-overwriting
+- [ ] Validation still fails closed (unknown params rejected, capability errors explicit)
+- [ ] Bounded output still reports truncation (`omitted`, `truncated`, `contextStats`)
+- [ ] Page-derived text stays marked `untrustedContent`; no typed values recorded in flows
+- [ ] Behaviour is identical on both engines, or the difference is an explicit `UNSUPPORTED_CAPABILITY`
+
+## Housekeeping
+
+- [ ] Backlog item checked off in `docs/roadmap/improvements-backlog.md`
+- [ ] Architecture-decision entry added, if this changes a settled decision or the agent-facing contract
+- [ ] A new protocol command was added to *both* hosts, the validator, the CLI, help text, and `capabilities`
+- [ ] Docs updated — phase contract, README, and every duplicated copy on the site
+- [ ] No committed media outside regenerated `docs/qa/evidence/` (checksums updated if so)
@@ -0,0 +1,47 @@
+version: 2
+
+updates:
+  # The Swift package has zero third-party dependencies by design, so there is
+  # nothing to update there — see docs/roadmap/what-is-excellent.md §11.
+  - package-ecosystem: npm
+    directory: /apps/web
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:chore"
+      - "area:web"
+    groups:
+      react:
+        patterns: ["react", "react-dom", "@types/react", "@types/react-dom"]
+      next:
+        patterns: ["next", "eslint-config-next"]
+      tailwind:
+        patterns: ["tailwindcss", "@tailwindcss/*"]
+      types:
+        patterns: ["@types/*"]
+
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 3
+    labels:
+      - "type:chore"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - "type:ci"
+
+  - package-ecosystem: docker
+    directory: /apps/headless
+    schedule:
+      interval: monthly
+    labels:
+      - "type:ci"
+      - "area:build-release"
@@ -21,6 +21,8 @@ Read before making non-trivial changes:
   stays Swift; don't propose rewrites).
 - `docs/roadmap/improvements-backlog.md` — known defects with file/line refs;
   check items off when you fix them and add the named test.
+- `CONTRIBUTING.md` — the same rules for humans, plus setup detail.
+- `SECURITY.md` — the boundaries a bug report is measured against.
 - To *use* Headless as a browser tool (rather than develop it), follow the
   skill: `.agents/skills/headless-computer-use/SKILL.md`.
 
@@ -62,6 +64,21 @@ Docker E2E. The macOS WKWebView E2E is heavier — it runs nightly, on
 `workflow_dispatch`, or when a PR carries the `macos-e2e` label. Run it that
 way before merging changes to `main.swift`, `Host/`, or capture code.
 
+## Picking up work
+
+Every open backlog item is a GitHub issue labelled `backlog`, cross-linked
+from the backlog file in both directions, carrying type/area/priority labels
+and sitting in the milestone for its roadmap phase. Work from either surface —
+but when you fix something, close the issue **and** check the item off in
+`docs/roadmap/improvements-backlog.md` in the same PR, so the two never drift.
+
+Phase 1 (`Trust the build`) is the current milestone; `priority:critical` and
+`priority:high` items there come first. `good first issue` marks the
+self-contained ones.
+
+Anything that changes the agent-facing contract needs an entry in
+`docs/roadmap/architecture-decisions.md` before the code lands.
+
 ## Hard rules (host-enforced contracts — never weaken)
 
 1. No arbitrary-JS execution verb; no TCP listener; no Chromium debug port.

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to Headless are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Releases are tagged `vX.Y.Z` and published by
+[`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+Two versions travel independently, on purpose:
+
+- **Product version** — the git tag, flowing into the macOS `Info.plist` via
+  `HEADLESS_VERSION` and into release assets.
+- **Protocol version** — `headlessProtocolVersion` in `Protocol.swift`,
+  currently `0.4`. It changes only when the wire contract changes, and always
+  with an entry in
+  [`docs/roadmap/architecture-decisions.md`](docs/roadmap/architecture-decisions.md).
+
+## [Unreleased]
+
+Everything below has landed on `main` but is **not yet in a tagged release**.
+Cutting that release is tracked in
+[#45](https://github.com/LockInTime/headless/issues/45).
+
+### Added
+
+- Progressive context pruning: `inspect --context summary|outline|text|actions|full`
+  with `--task` ranking, `--within @rN` scoping, and `--limit` / `--budget` /
+  `--depth` bounds. Every focused response reports `contextStats` and `omitted`.
+  Measured 94.5 % estimated-token reduction on the 120-section fixture.
+- Capture formats: JPG/JPEG and PDF screenshots, `--every-viewport` and
+  `--by-section` screenshot series, and MOV/WebM/GIF recording containers.
+- Product documentation set — [`docs/ROADMAP.md`](docs/ROADMAP.md),
+  [what is excellent](docs/roadmap/what-is-excellent.md),
+  [architecture decisions](docs/roadmap/architecture-decisions.md), and the
+  [improvements backlog](docs/roadmap/improvements-backlog.md).
+- Contributor rule files for every coding harness: [`AGENTS.md`](AGENTS.md)
+  and `CLAUDE.md`.
+- Continuous integration on every pull request
+  ([`ci.yml`](.github/workflows/ci.yml)): static checks, agent-runtime suite,
+  protocol suite on Linux and macOS, web lint and build, and the Linux Docker
+  E2E. The macOS WKWebView E2E runs nightly or on the `macos-e2e` label.
+- Repository governance: MIT `LICENSE` preserving the upstream chromeless
+  notice, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue forms,
+  a pull-request template, `CODEOWNERS`, and Dependabot.
+
+### Changed
+
+- QA evidence now includes a recorded progressive-pruning scenario, and the
+  committed bundle is checksum-verified in CI.
+- Repository moved to the `LockInTime` organisation; site links updated.
+
+### Known gaps
+
+Tracked as [`backlog`](https://github.com/LockInTime/headless/labels/backlog)
+issues, grouped by roadmap phase into milestones. Highlights:
+a shutdown data race on the Linux host
+([#12](https://github.com/LockInTime/headless/issues/12)), responses that can
+exceed the 1 MiB frame ([#14](https://github.com/LockInTime/headless/issues/14)),
+and unsigned macOS builds
+([#39](https://github.com/LockInTime/headless/issues/39)).
+
+## [1.0.2] — 2026-07-19
+
+### Fixed
+
+- macOS: recover when a restored page is unavailable at launch.
+
+## [1.0.1] — 2026-07-19
+
+### Fixed
+
+- Release CI: harden the macOS E2E suite for GitHub runners.
+
+## [1.0.0] — 2026-07-19
+
+First tagged release: the P0–P2 contract on macOS and Linux.
+
+### Added
+
+- Persistent host with a versioned JSON protocol over a private per-user Unix
+  socket, peer-UID checked, with no TCP listener and no arbitrary-JavaScript
+  verb.
+- Two engines behind one CLI contract: macOS WKWebView windows, Linux
+  sandboxed Chromium driven over the inherited DevTools fd-3/4 pipe.
+- Semantic interaction — `visit`, `inspect`, `click`, `fill`, `press`,
+  `scroll`, `wait`, `tour`, `back`, `reload` — targeted by role/name or by
+  element reference.
+- Evidence capture: screenshots, built-in FFmpeg recording, visual comparison,
+  flows, and QA reports, written to a `0700` per-user artifact store with
+  `0600` non-overwriting files.
+- Diagnostics with redaction: console, network, cookies, storage, computed
+  styles, performance, and animations. Sensitive values are double-gated.
+- Linux-only network emulation and request mocking; macOS returns
+  `UNSUPPORTED_CAPABILITY` rather than partially emulating.
+- `headless-mcp`, a stdio MCP server exposing the CLI as a single `argv` tool.
+- Snap Chromium rejection before launch, after it proved unreliable over the
+  DevTools pipe.
+- Tag-triggered release workflow publishing a macOS app zip and Linux
+  amd64/arm64 tarballs.
+
+[Unreleased]: https://github.com/LockInTime/headless/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/LockInTime/headless/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/LockInTime/headless/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/LockInTime/headless/releases/tag/v1.0.0