orbit-thread 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.2.0 — 12 October 2026
+
+- Add **Orbit Resume**, a third canonical skill that recovers project context at the start of a fresh Codex or Claude Code session from the latest usable handoff, current Git state and only the living docs the task needs.
+- Add read-only `npx orbit-thread resume` for a concise terminal summary of handoff, Git state and next action.
+- Invoke manually with `$orbit-resume` (Codex), `/orbit-resume` (Claude Code) or `/orbit-thread:orbit-resume` (Claude marketplace plugin). Invocation can also be automatic where the host supports implicit skill invocation (`allow_implicit_invocation: true`); manual invocation is the documented fallback.
+- Treat the handoff as a lead: current Git state and tracked docs override stale details, and missing, malformed, stale or future-dated handoffs are reported rather than guessed.
+- Security safeguards: Resume is read-only and never resets, cleans, stashes, stages, commits or otherwise changes the working tree; it strips terminal-control sequences from displayed repository and handoff text, redacts secret-looking values, and does not read `.env` files, credentials or unrelated files.
+- Install, update, Doctor and uninstall now manage all three skills (`handoff`, `orbit-setup`, `orbit-resume`) for both agents.
+- Backwards compatible: existing v1.1.0 installations, `HANDOFF-STATE.md` files, `.orbit-thread/config.json` and living docs keep working unchanged; `orbit-thread update` adds Resume without touching locally edited managed files, and `orbit-handoff` remains a CLI alias.
+
 ## 1.1.0 — 7 October 2026
 
 - Rename the product from **Orbit Handoff** to **Orbit Thread**.

package/PRIVACY.md

@@ -1,9 +1,83 @@
-# Privacy
+# Privacy Policy
 
-Orbit Thread has no telemetry, remote service, external account or MCP server.
+Last updated: 7 October 2026
 
-The Handoff writer processes input locally and saves `HANDOFF-STATE.md`. Orbit Setup writes local/project documentation, managed agent instructions, a small project configuration file and local ownership state. The CLI records hashes and the exact managed instruction blocks it adds.
+## Overview
 
-Installation through npm or a plugin marketplace uses the relevant registry or Git host. Your coding agent's model calls and privacy settings remain governed by its provider. Orbit Thread's local writer and setup/configuration scripts do not send repository content anywhere.
+Orbit Thread is a local-first developer tool for project setup, coding-session continuity and verified handoffs.
 
-Keep secrets, credentials, personal data and sensitive production data out of handoffs and living docs. Pattern checks are limited and are not a data-loss-prevention system. `HANDOFF-STATE.md` and Orbit Thread's local ownership state are Git-ignored by setup; ignoring a previously tracked file does not untrack it.
+Orbit Thread does not operate a remote service, require an Orbit Thread account, run an MCP server, or collect telemetry or analytics.
+
+## Data Orbit Thread processes
+
+Orbit Thread does not collect or transmit user or repository content to an Orbit Thread-operated server.
+
+When used in a coding project, Orbit Thread may process information that the user or coding agent makes available locally in order to:
+
+- create or update project documentation and managed agent instructions;
+- create and overwrite `HANDOFF-STATE.md`;
+- store project configuration and local ownership state;
+- record hashes and exact managed instruction blocks for safe updates and uninstall operations.
+
+This information may include project names, source-code context, technical decisions and other information intentionally included in project documentation or handoffs.
+
+Orbit Thread is not designed to collect or process payment-card information, protected health information, government identifiers, passwords, API keys, authentication tokens, MFA/OTP codes, recovery codes or other authentication secrets. Users should not place this information in Orbit Thread handoffs or living project documents.
+
+Secret-pattern checks are a limited safety backstop and are not a data-loss-prevention system.
+
+## Purposes of processing
+
+Orbit Thread processes local project information only as necessary to:
+
+- prepare a project for coding-agent continuity;
+- maintain concise project and execution state;
+- safely install, update and uninstall Orbit Thread-managed files;
+- verify ownership of managed content and avoid overwriting unrelated or locally modified files.
+
+Orbit Thread does not use project information for advertising, behavioural profiling, analytics, model training or sale to third parties.
+
+## Sharing and recipients
+
+Orbit Thread itself does not transmit repository content, handoffs or local project documentation to the developer of Orbit Thread or to an Orbit Thread-operated service.
+
+Installation or distribution may involve third-party services such as npm, GitHub, OpenAI or Anthropic. Those services process information according to their own privacy policies and service settings.
+
+When Orbit Thread is used through a coding agent, information intentionally provided to that agent may be processed by the agent provider under that provider's privacy settings and terms. Orbit Thread's local scripts do not independently transmit repository content to those providers.
+
+## Data retention
+
+Orbit Thread does not retain user or project data on developer-operated servers because Orbit Thread operates no such service.
+
+Local data remains on the user's device or project until the user removes it or the relevant file is overwritten.
+
+`HANDOFF-STATE.md` is overwrite-only and is replaced when a new successful checkpoint is created.
+
+Project documentation and `.orbit-thread` configuration may remain after Orbit Thread is uninstalled so that project-owned information is not destroyed automatically. Users may delete these files at any time.
+
+Retention by npm, GitHub, OpenAI, Anthropic or other third-party services is governed by those services' own policies.
+
+## User controls
+
+Users control the project information made available to Orbit Thread.
+
+Users may inspect, edit or delete Orbit Thread-created local files at any time, including `HANDOFF-STATE.md`, project documentation and `.orbit-thread` configuration.
+
+Orbit Thread can also be uninstalled using its CLI. Uninstall intentionally preserves project-owned documentation and configuration unless the user chooses to delete them separately.
+
+Orbit Thread setup Git-ignores `HANDOFF-STATE.md` and local ownership state. Adding an already tracked file to `.gitignore` does not remove it from Git history or stop Git from tracking it.
+
+## Security and sensitive information
+
+Do not place passwords, authentication secrets, private keys, recovery codes, personal data or sensitive production information in handoffs or living project documents.
+
+Orbit Thread includes limited pattern checks intended to reduce accidental inclusion of obvious secrets, but these checks do not guarantee detection of sensitive data.
+
+## Changes to this policy
+
+This policy may be updated when Orbit Thread's functionality or data practices change. Material changes will be reflected in this document and its Git history.
+
+## Contact
+
+Privacy or security questions can be raised through the Orbit Thread GitHub repository:
+
+https://github.com/shab1h-gh/orbit-thread/issues

package/README.md

@@ -1,53 +1,91 @@
-# Orbit Thread
+# 🧵 Orbit Thread
 
-**Keep coding agents aligned across long projects without carrying a huge conversation forever.**
+**Pick up where you left off, without carrying an entire coding conversation into the next session.**
 
-[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/orbit-thread?label=npm)](https://www.npmjs.com/package/orbit-thread)
 [![CI](https://github.com/shab1h-gh/orbit-thread/actions/workflows/ci.yml/badge.svg)](https://github.com/shab1h-gh/orbit-thread/actions/workflows/ci.yml)
+[![MIT licence](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
 
-Orbit Thread is a small local continuity layer for Codex and Claude Code. It has two reusable skills:
+Orbit Thread helps **Codex** and **Claude Code** keep their place during long projects. It gives each project a small set of useful documents and saves a short handoff when the agent reaches a verified checkpoint.
 
-- **Orbit Setup** prepares a project with lightweight living documentation and token-efficient agent rules.
-- **Handoff** keeps one short `HANDOFF-STATE.md` current so a fresh session can resume from verified state instead of replaying a large chat history.
+No giant session diary. No separate account or hosted memory service. Your repository and Git history remain the source of truth.
 
-Tracked source, Git history and living project docs remain authoritative. The handoff is current execution state, not a changelog.
+| Skill | What it does |
+| --- | --- |
+| 🧭 **Orbit Setup** | Prepares project docs, agent instructions and optional subagent preferences. |
+| 🔁 **Handoff** | Records the current objective, completed work, risks and next actions in `HANDOFF-STATE.md`. |
+| ▶️ **Resume** | Reconstructs concise current context from the handoff and read-only Git state. |
+
+**Jump to:** [Quick start](#quick-start) · [How it works](#how-it-works) · [Setup files](#what-setup-creates) · [Handoff and Resume](#handoff-and-resume) · [Subagents](#configure-subagents) · [Doctor](#check-your-setup) · [Commands](#command-reference) · [Help](#troubleshooting)
 
 ## Quick start
 
-From the project you want to configure:
+> 🚀 Run these commands **inside the project** you want to set up.
 
-```sh
+```bash
 npx orbit-thread install
 npx orbit-thread setup
 ```
 
-Choose Codex, Claude Code or both when prompted.
-
-Non-interactive:
+Choose Codex, Claude Code or both when prompted. To skip the questions:
 
-```sh
+```bash
 npx orbit-thread install --agent both --scope project --yes
 npx orbit-thread setup --agent both --yes
 ```
 
-Then use the skills directly:
+Once installed, call the skills in your coding agent:
+
+| Where you're working | Set up a project | Save a handoff | Resume a fresh chat |
+| --- | --- | --- | --- |
+| Codex | `$orbit-setup` | `$handoff` | `$orbit-resume` |
+| Claude Code | `/orbit-setup` | `/handoff` | `/orbit-resume` |
+| Claude marketplace plugin | `/orbit-thread:orbit-setup` | `/orbit-thread:handoff` | `/orbit-thread:orbit-resume` |
+
+The commands above are **skill invocations**, not Terminal commands. You can also ask the agent to run a handoff after a verified milestone.
+
+## How it works
+
+Orbit Thread keeps **lasting project knowledge** separate from **what the agent is doing right now**.
+
+```text
+Existing project
+      │
+      ▼
+Orbit Setup
+      │
+      ├── Living docs and agent instructions
+      └── Project preferences
+      │
+      ▼
+Agent completes verified work
+      │
+      ▼
+Handoff rewrites HANDOFF-STATE.md
+      │
+      ▼
+Next session checks handoff + Git + relevant docs
+      │
+      ▼
+Continue from the last verified point
+```
+
+The important distinction:
 
-| Agent | Setup | Handoff |
-| --- | --- | --- |
-| Codex standalone | `$orbit-setup` | `$handoff` |
-| Claude Code standalone | `/orbit-setup` | `/handoff` |
-| Claude plugin | `/orbit-thread:orbit-setup` | `/orbit-thread:handoff` |
+- **Git** keeps the history of code and decisions.
+- **Living docs** describe the project as it stands today.
+- **`HANDOFF-STATE.md`** says where the current task stands and what needs doing next.
 
-## What Orbit Setup creates
+The handoff is a checkpoint, **not** another changelog or a substitute for Git. If the handoff is stale, the current repository state wins.
 
-Orbit Setup is designed to run before the first substantial coding prompt, or later to upgrade an existing project.
+## What setup creates
 
-If equivalent files do not already exist, it creates:
+Orbit Setup can prepare a new project or add the workflow to an existing one. It creates missing files without duplicating equivalent documents already in the repository root or `docs/`.
 
 ```text
 project/
 ├── AGENTS.md
-├── CLAUDE.md                 # when Claude is selected
+├── CLAUDE.md                 # if Claude Code is selected
 ├── .orbit-thread/
 │   └── config.json           # tracked project preferences
 └── docs/
@@ -58,62 +96,37 @@ project/
     └── ROADMAP.md
 ```
 
-At the first meaningful checkpoint, Handoff creates:
+The first successful Handoff also creates `HANDOFF-STATE.md`. That file and Orbit Thread's local ownership state are ignored by Git.
 
-```text
-HANDOFF-STATE.md              # local, Git-ignored, overwrite-only
-```
-
-Orbit Thread also keeps its small internal ownership state local and Git-ignored.
-
-Existing product/design/architecture/security/roadmap files at either the repository root or under `docs/` are preserved instead of duplicated.
-
-### Living-doc rules
-
-The generated project instructions tell the agent to:
+### Which document should change?
 
-- load only the docs relevant to the current task;
-- inspect only the source files it actually needs;
-- keep `PRODUCT.md`, `DESIGN.md`, `ARCHITECTURE.md`, `SECURITY.md` and `ROADMAP.md` as current truth;
-- update affected sections **in place** after verified changes;
-- never append session diaries or duplicate superseded sections;
-- keep Git as history;
-- never rewrite an applied migration;
-- run the smallest relevant verification before claiming completion.
-
-The document-routing rules are deliberately selective:
-
-- product behaviour, copy or scope → `PRODUCT.md`
-- UI/UX → `DESIGN.md`
-- runtime, data flow, infrastructure or integrations → `ARCHITECTURE.md`
-- auth, tenancy, secrets or other security-sensitive work → `SECURITY.md`
-- future planning only → `ROADMAP.md`
-
-This keeps routine tasks from loading every project document into context.
+| Work completed | Update |
+| --- | --- |
+| Product behaviour, copy or scope | `PRODUCT.md` |
+| Interface, layouts or user experience | `DESIGN.md` |
+| Runtime, data flow or integrations | `ARCHITECTURE.md` |
+| Authentication, permissions or secrets handling | `SECURITY.md` |
+| Plans that have not been implemented | `ROADMAP.md` |
 
-## Checkpoints and fresh-context recovery
+The generated instructions ask coding agents to read only the documents and source files they need. After verified changes, they should **update the relevant sections in place**, not pile new notes underneath old ones.
 
-Orbit Thread asks the coding agent to run Handoff:
+They also tell agents to preserve applied migrations, leave history to Git and run an appropriate check before claiming work is finished.
 
-- after a meaningful verified milestone that changed repository state or durable project truth;
-- after a completed coding task with such changes, before the final reply;
-- before `/clear`, session end, or a usage/context stop when the agent receives warning.
+## Handoff and Resume
 
-It intentionally skips read-only questions and trivial edits.
+### When to save a handoff
 
-Each successful checkpoint **overwrites** the previous `HANDOFF-STATE.md`. It does not grow into a development diary.
+Handoff is intended for moments that matter:
 
-After a fresh, cleared or recovered session, the generated project rules tell the agent to recover in this order:
+- After a verified milestone that changes the repository or lasting project information.
+- At the end of a coding task that made those changes.
+- Before clearing a session or stopping because of a usage or context warning.
 
-1. read `HANDOFF-STATE.md` once if present;
-2. inspect current branch/status/diff/recent Git log;
-3. load only relevant living docs;
-4. inspect only source needed for the recorded next action;
-5. preserve valid uncommitted work and continue from the highest verified milestone.
+It is not necessary for ordinary questions or tiny edits with no lasting effect. Each successful checkpoint **replaces** the previous handoff.
 
-## Handoff format
+### What gets saved?
 
-A handoff is normally about 30 lines and has a hard cap of 50:
+Handoffs are usually around 30 lines, with a **hard limit of 50 lines**.
 
 ```markdown
 # Handoff State
@@ -121,14 +134,14 @@ A handoff is normally about 30 lines and has a hard cap of 50:
 Updated: 07-10-2026 00:30
 
 ## Current objective
-- Finish account-security settings.
+- Finish account security settings.
 
 ## Completed milestones
 - Added the settings route.
-- Connected password change and session revocation.
+- Connected password changes and session revocation.
 
 ## In progress
-- Passkey-management UI.
+- Passkey management UI.
 
 ## Open issues / risks
 - Passkey removal still needs a browser test.
@@ -142,115 +155,158 @@ Updated: 07-10-2026 00:30
 - Unit tests passed: 42/42.
 ```
 
-The writer validates before replacing the previous handoff, rejects obvious secret-like content, writes atomically, makes no network calls and does not mutate Git.
-
-## Subagent configuration
+The writer validates the replacement before saving it, checks for recognisable secret patterns and writes the file atomically. **It makes no network requests and does not change Git.** Secret detection is a safety net, not a guarantee; never put sensitive data in a handoff.
 
-Orbit Thread defaults to **no subagents unless they genuinely help**, with a maximum of two and no recursive subagents.
+### Starting a fresh session
 
-You can save project-specific model/reasoning preferences without hand-editing `AGENTS.md`:
+Start each new coding task in a fresh chat. Orbit Setup asks the agent to invoke Resume once when the session starts (automatically where the host supports it). If it does not start automatically, use `$orbit-resume`, `/orbit-resume`, or `/orbit-thread:orbit-resume` in Claude marketplace installs. Do not invoke it repeatedly in the same session.
 
-```sh
-npx orbit-thread configure --agent claude \
-  --model "Claude Sonnet 5.5" --effort low
+For a terminal summary, run:
 
-npx orbit-thread configure --agent codex \
-  --model "GPT-6.1 Sol" --reasoning high
+```bash
+npx orbit-thread resume
 ```
 
-Change the maximum:
+Resume prints the handoff objective, verified milestones, unfinished work, risks, verification, current branch and working-tree status, next steps and relevant living-doc paths. It is read-only: it does not modify files or Git, install tools, deploy, or inspect secret files. It uses current repository evidence over stale handoff details, flags a handoff that appears older than the latest commit, and preserves dirty changes. If the handoff is absent or invalid, it says what is unknown rather than guessing.
 
-```sh
-npx orbit-thread configure --max-subagents 1
+This lightweight checkpoint saves tokens by replacing repeated conversation history with a short summary and only the project documents the next task needs. It cannot recover details that were never recorded, prove that an unrecorded check passed, or determine the user's next goal when none was stated. Use the current request as the objective and say when evidence is missing.
+
+The project instructions ask the agent to:
+
+1. Use the Resume summary or read `HANDOFF-STATE.md` once if no summary was supplied.
+2. Check the branch, working tree, diff summary and recent Git history.
+3. Read only living docs relevant to the current task.
+4. Inspect only source needed for the next action.
+5. Preserve unfinished work and continue from the latest verified point.
+
+You do not need to paste an old conversation into the next session.
+
+## Configure subagents
+
+Orbit Thread only **records preferences**. It does not launch subagents itself.
+
+By default, agents should use helpers only when the work warrants them. The configured maximum is **two**, and helpers should not spawn further helpers.
+
+**Set the limit:**
+
+```bash
+npx orbit-thread configure --max-subagents 2
 ```
 
-Disable subagents:
+**Turn subagents off:**
 
-```sh
+```bash
 npx orbit-thread configure --max-subagents 0
 ```
 
-Show configuration:
+**Save preferred models and reasoning:**
+
+```bash
+npx orbit-thread configure --agent codex --model "GPT-6 Luna" --reasoning high
+npx orbit-thread configure --agent claude --model "Claude Sonnet 5.5" --effort medium
+```
+
+**Check the saved settings:**
 
-```sh
+```bash
 npx orbit-thread configure --show
 ```
 
-Reset saved subagent preferences:
+**Reset one agent's preferences:**
 
-```sh
+```bash
 npx orbit-thread configure --agent claude --reset-subagents
 ```
 
-Preferences are stored in `.orbit-thread/config.json` and reflected in Orbit Thread's managed section of `AGENTS.md`. They are preferences rather than hard dependencies: an unavailable exact model setting should not block useful work.
+The settings live in `.orbit-thread/config.json` and are reflected in Orbit Thread's managed section of `AGENTS.md`. They are preferences, not requirements. If a named model is unavailable, the agent can use a suitable alternative.
 
-## Project doctor
+## Check your setup
 
-Run:
+> 🩺 **Doctor** checks Orbit Thread itself. It does not test whether your application works.
 
-```sh
-npx orbit-thread doctor
+Run it after installing, updating, changing configuration or moving to a fresh checkout:
+
+```bash
+npx orbit-thread doctor --agent both --scope project
 ```
 
-It checks the managed skill installation and project continuity setup, including living docs, config, managed agent blocks, Git-ignore rules, duplicate root/docs files and handoff size.
+Or check each integration separately:
 
-`npx orbit-thread check` remains the lightweight managed-skill installation check kept for Orbit Handoff compatibility; use `doctor` for the full project health check.
+```bash
+npx orbit-thread doctor --agent codex --scope project
+npx orbit-thread doctor --agent claude --scope project
+```
 
-## Installation
+Doctor checks skill versions (including Resume), project configuration, managed instruction blocks, living docs, Git ignore rules and handoff size.
 
-Requirements:
+**How do you know it passed?** A successful command exits with status `0`. To print a clear confirmation:
 
-- Node.js 20+
-- Git for normal repository workflows
-- a POSIX shell and standard Unix utilities for the handoff writer
+```bash
+npx orbit-thread doctor --agent both --scope project && echo "Orbit Thread Doctor passed"
+```
 
-macOS and Linux are supported. Native Windows is not currently supported; WSL is the expected route.
+A nonzero result means the continuity setup needs attention. It does **not** necessarily mean your app or deployment is broken.
 
-### npm / standalone Codex and Claude Code
+For a quicker check of installed managed skills only:
 
-```sh
-npx orbit-thread install
+```bash
+npx orbit-thread check
 ```
 
-Project installs use:
+## Installation options
+
+### Requirements
 
-| Agent | Project location |
+- **Node.js 20 or later**
+- **Git** for normal repository work
+- **POSIX shell and standard Unix tools** for the handoff writer
+
+Orbit Thread supports **macOS and Linux**. For Windows, use **WSL**; native Windows is not currently supported.
+
+### npm for Codex or Claude Code
+
+```bash
+npx orbit-thread install
+```
+
+| Agent | Project skill directories |
 | --- | --- |
-| Codex | `.agents/skills/handoff/` and `.agents/skills/orbit-setup/` |
-| Claude Code | `.claude/skills/handoff/` and `.claude/skills/orbit-setup/` |
+| Codex | `.agents/skills/handoff/`, `.agents/skills/orbit-setup/` and `.agents/skills/orbit-resume/` |
+| Claude Code | `.claude/skills/handoff/`, `.claude/skills/orbit-setup/` and `.claude/skills/orbit-resume/` |
 
-User/global installs use the equivalent `~/.agents/skills/` or `~/.claude/skills/` locations.
+A user level install uses the equivalent directories under `~/.agents/skills/` or `~/.claude/skills/`.
 
 ### Claude GitHub marketplace
 
-Inside Claude Code:
+In **Claude Code**, run:
 
 ```text
 /plugin marketplace add shab1h-gh/orbit-thread
 /plugin install orbit-thread@orbit-thread
 ```
 
-Equivalent shell commands:
+Or use these Terminal commands:
 
-```sh
+```bash
 claude plugin marketplace add shab1h-gh/orbit-thread
 claude plugin install orbit-thread@orbit-thread
 ```
 
-The GitHub marketplace route is separate from Anthropic's official public directory.
+This GitHub marketplace route is separate from the **official Anthropic public directory**. Installing from GitHub does not mean the plugin has been approved for that directory.
 
-## Commands
+## Command reference
 
 | Command | Purpose |
 | --- | --- |
-| `npx orbit-thread install` | Install both skills for selected agent(s). |
-| `npx orbit-thread setup` | Prepare/upgrade the current project workflow and living docs. |
-| `npx orbit-thread configure` | Configure project subagent preferences. |
-| `npx orbit-thread doctor` | Check installation and project continuity health. |
-| `npx orbit-thread@latest update` | Upgrade unchanged managed skill files. |
-| `npx orbit-thread uninstall` | Remove managed skills/instruction blocks while preserving project-owned docs/config/state. |
-| `npx orbit-thread init` | Backwards-compatible alias for `setup`. |
-| `npx orbit-thread check` | Check managed skill installation (kept for Orbit Handoff compatibility). |
+| `npx orbit-thread install` | Install the three skills for selected agents. |
+| `npx orbit-thread setup` | Prepare or update project docs and managed instructions. |
+| `npx orbit-thread resume` | Print a concise, read-only project and Git summary. |
+| `npx orbit-thread configure` | Save project subagent preferences. |
+| `npx orbit-thread doctor` | Check the project's continuity setup. |
+| `npx orbit-thread check` | Check managed skill installation only. |
+| `npx orbit-thread@latest update` | Update managed skills that have not been locally changed. |
+| `npx orbit-thread uninstall` | Remove managed skills and blocks, preserving project docs and state. |
+| `npx orbit-thread init` | Older alias for `setup`. |
 
 Common options:
 
@@ -260,61 +316,134 @@ Common options:
 --yes
 ```
 
-## Migrating from Orbit Handoff 1.0.x
+### Update an existing installation
+
+```bash
+npx orbit-thread@latest update --agent both --scope project --yes
+npx orbit-thread@latest setup --agent both --yes
+npx orbit-thread doctor --agent both --scope project
+```
 
-Orbit Thread is the successor to **Orbit Handoff**.
+The update command protects locally edited managed skill files. Setup updates managed project instructions and creates missing living docs without replacing existing equivalents.
 
-Existing npm-managed users should install/update through the new package name:
+### Moving from Orbit Handoff 1.0.x
 
-```sh
+Orbit Thread is the successor to **Orbit Handoff**. The v1.1 and later CLI recognises compatible older managed installations and state while preserving local edits.
+
+```bash
 npx orbit-thread@latest update --agent both --scope project --yes
 npx orbit-thread@latest setup --agent both --yes
 npx orbit-thread doctor --agent both --scope project
 ```
 
-The v1.1 CLI recognises the managed Orbit Handoff installation/state and migrates it without intentionally overwriting local edits. The old `orbit-handoff` binary name remains an alias inside the Orbit Thread package for compatibility.
+The old `orbit-handoff` binary name remains an alias inside the new package. Earlier npm releases remain unchanged.
 
-The historical `orbit-handoff` npm releases remain immutable.
+If you installed the Claude GitHub marketplace plugin, update or reinstall it from `shab1h-gh/orbit-thread` and run `/orbit-thread:orbit-setup`.
 
-For Claude GitHub-marketplace users, update/reinstall from the renamed repository and run:
+## Troubleshooting
 
-```text
-/orbit-thread:orbit-setup
+<details>
+<summary><strong>Doctor reports a changed AGENTS.md or CLAUDE.md block</strong></summary>
+
+A Markdown formatter can change whitespace inside an Orbit Thread managed block. That can fail the integrity check even when the text looks fine.
+
+Inspect the changes first:
+
+```bash
+git diff -- AGENTS.md CLAUDE.md
 ```
 
-## Updating Orbit Thread
+**Only if those files have no work you need to keep**, restore them and rerun setup:
 
-```sh
-npx orbit-thread@latest update --agent both --scope project --yes
-npx orbit-thread@latest setup --agent both --yes
+```bash
+git restore -- AGENTS.md CLAUDE.md
+npx orbit-thread setup --agent both --yes
+npx orbit-thread doctor --agent both --scope project
 ```
 
-The first command updates unchanged managed skill files. The second updates the project-managed rules and creates only missing living docs.
+If you have intentional edits, do **not** restore the whole files. Repair only the affected managed block, then rerun setup and Doctor. Consider excluding `AGENTS.md` and `CLAUDE.md` from Prettier using `.prettierignore`.
+
+</details>
+
+<details>
+<summary><strong>Setup refuses to overwrite a managed block</strong></summary>
 
-Locally edited managed skill files are never force-overwritten.
+That protection is deliberate. Orbit Thread will not replace a block it can no longer confirm it owns.
+
+Review the block and its markers, preserve your own instructions, repair the managed portion and run:
+
+```bash
+npx orbit-thread setup --agent both --yes
+npx orbit-thread doctor --agent both --scope project
+```
+
+Do not delete `.orbit-thread/state.json` or remove markers to get around the check.
+
+</details>
+
+<details>
+<summary><strong>My handoff was rejected</strong></summary>
+
+Keep `HANDOFF-STATE.md` at **50 lines or fewer**. Remove credentials, tokens, keys and sensitive personal or production information, then retry. The previous successful handoff is preserved when validation fails.
+
+</details>
+
+<details>
+<summary><strong>Does Orbit Thread synchronise chats across agents?</strong></summary>
+
+No. It keeps project documents and a local handoff that agents can read. It does not copy conversation history between Codex and Claude Code. A fresh session should check the handoff and Git rather than assume it has the earlier chat's context.
+
+</details>
+
+<details>
+<summary><strong>What if a configured model is unavailable?</strong></summary>
+
+The subagent model and reasoning values are suggestions, not enforced settings. Use an appropriate available model and keep the configured helper limit.
+
+```bash
+npx orbit-thread configure --show
+```
+
+</details>
+
+<details>
+<summary><strong>npm reports a cache permission error</strong></summary>
+
+Try the Doctor command in your normal Terminal and check npm's cache before changing any permissions:
+
+```bash
+npm config get cache
+npm cache verify
+```
+
+A restricted coding environment may report a permissions error even when your Mac's cache is healthy. Do not run npm with `sudo` or change ownership without identifying the failing path.
+
+</details>
 
 ## Security and privacy
 
-Orbit Thread is local-first.
+> 🔒 Orbit Thread's handoff writer runs locally. It does not send files to an Orbit Thread service, collect telemetry or alter Git.
 
-The handoff writer makes no network calls and does not mutate Git. Secret detection is a backstop, not a data-loss-prevention system, so never place credentials, personal data or sensitive production information in handoffs or project docs.
+The installer protects unmanaged skills and locally modified managed files. Setup leaves unrelated instructions and existing project documents alone.
 
-The installer refuses unmanaged skill collisions and protects locally modified managed files. Setup preserves unrelated instructions and existing project docs.
+The secret checker catches some recognisable patterns, **not every type of sensitive information**. Do not include passwords, API keys, recovery codes, personal data or production secrets in handoffs or living docs.
 
-There is no Orbit Thread telemetry. npm, GitHub, Claude and OpenAI still operate under their own service/privacy policies.
+Installing packages or using a coding agent can still involve **npm, GitHub, OpenAI or Anthropic** under those providers' own terms and privacy policies.
 
-See [SECURITY.md](SECURITY.md) and [PRIVACY.md](PRIVACY.md).
+Read [Security](SECURITY.md) and [Privacy](PRIVACY.md) for the details.
 
 ## Provider directories
 
-The repository includes a portable skills-only plugin ZIP suitable for OpenAI's plugin upload flow and a Claude plugin manifest suitable for Anthropic/GitHub distribution.
+The repository includes a portable skills plugin ZIP for the OpenAI upload flow and a Claude plugin manifest for Anthropic and GitHub distribution.
 
-Public OpenAI and Anthropic directory approval is separate from npm/GitHub installation. See [docs/SUBMISSION.md](docs/SUBMISSION.md).
+**Submission, approval and publication are separate steps.** A working npm or GitHub installation does not establish that a plugin is publicly listed by OpenAI or Anthropic. See [directory submission notes](docs/SUBMISSION.md).
 
 ## Contributing
 
-Issues and focused pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+Bug reports, documentation improvements and focused pull requests are welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), or [open an issue](https://github.com/shab1h-gh/orbit-thread/issues).
 
 ## Licence
 
-[MIT](LICENSE) — Shabih Anwar.
+[MIT](LICENSE). Created by **Shabih Anwar**.

package/docs/PUBLISHING.md

@@ -1,8 +1,10 @@
 # npm publication and releases
 
-Orbit Thread v1.1.0 is the successor to Orbit Handoff v1.0.x.
+Orbit Thread v1.2.0 adds Orbit Resume to the Orbit Thread line, which succeeded Orbit Handoff v1.0.x in v1.1.0.
 
-Historical `orbit-handoff@1.0.0` and `orbit-handoff@1.0.1` releases are immutable. Do not republish, unpublish or move their release tags.
+`orbit-thread@1.1.0` is already published. v1.2.0 is a new version.
+
+Historical `orbit-handoff@1.0.0`, `orbit-handoff@1.0.1` and `orbit-thread@1.1.0` releases are immutable. Do not republish, unpublish or move their release tags.
 
 The new primary package is:
 
@@ -33,15 +35,18 @@ claude plugin validate . --strict
 Inspect:
 
 ```text
-orbit-thread-1.1.0.tgz
-dist/orbit-thread-plugin-1.1.0.zip
+orbit-thread-1.2.0.tgz
+dist/orbit-thread-plugin-1.2.0.zip
 ```
 
-Confirm both canonical skills are present:
+The npm tarball should contain 28 files (version 1.2.0, including `lib/resume.mjs` and `plugin/skills/orbit-resume/`). The plugin ZIP should contain the portable `plugin.json`, the three canonical skills and the listing icon. Neither should contain tests, `dist/`, credentials or other build residue.
+
+Confirm all three canonical skills are present:
 
 ```text
 plugin/skills/handoff/
 plugin/skills/orbit-setup/
+plugin/skills/orbit-resume/
 ```
 
 and that the packed CLI can install, setup, configure, doctor, update and uninstall in a disposable repository.
@@ -51,7 +56,7 @@ and that the packed CLI can install, setup, configure, doctor, update and uninst
 After release checks pass:
 
 ```sh
-npm publish ./orbit-thread-1.1.0.tgz --access public --registry https://registry.npmjs.org/
+npm publish ./orbit-thread-1.2.0.tgz --access public --registry https://registry.npmjs.org/
 ```
 
 Complete npm's normal browser/2FA challenge if prompted. Never weaken npm account security to automate publication.
@@ -73,7 +78,7 @@ npx orbit-thread@latest doctor --agent both --scope project
 npx orbit-thread@latest uninstall --agent both --scope project --yes
 ```
 
-Verify `latest` resolves to `1.1.0` and package metadata points to `shab1h-gh/orbit-thread`.
+Also confirm `npx orbit-thread@latest resume` runs read-only in the disposable repository. Verify `latest` resolves to `1.2.0` and package metadata points to `shab1h-gh/orbit-thread`.
 
 ## Existing Orbit Handoff users
 
@@ -85,7 +90,7 @@ npx orbit-thread@latest setup --agent both --yes
 npx orbit-thread doctor --agent both --scope project
 ```
 
-The v1.1 CLI accepts compatible Orbit Handoff ownership/project state and migrates it while refusing locally edited managed files.
+The v1.1 and later CLI accepts compatible Orbit Handoff ownership/project state and migrates it while refusing locally edited managed files.
 
 After Orbit Thread is publicly verified, the old package may be deprecated with a migration message, but must not be unpublished:
 

package/docs/SUBMISSION.md

@@ -1,15 +1,15 @@
 # Directory submission
 
-Updated 7 October 2026.
+Updated 12 October 2026.
 
 Provider-directory review is separate from npm, GitHub and standalone installation.
 
 ## OpenAI / ChatGPT Plugins Directory
 
-Orbit Thread v1.1.0 is submitted as:
+Orbit Thread v1.2.0 is submitted as:
 
 ```text
-dist/orbit-thread-plugin-1.1.0.zip
+dist/orbit-thread-plugin-1.2.0.zip
 ```
 
 Build it with:
@@ -18,14 +18,14 @@ Build it with:
 npm run build:plugin
 ```
 
-The ZIP contains portable `plugin.json`, both canonical skills, OpenAI interface metadata, the Orbit Setup onboarding skill, listing icon and compatibility metadata. Orbit Thread needs no MCP server or external account.
+The ZIP contains portable `plugin.json`, all three canonical skills, OpenAI interface metadata, the Orbit Setup onboarding skill, listing icon and compatibility metadata. Orbit Thread needs no MCP server or external account.
 
 ### Submission flow
 
-1. Complete release validation and build the final v1.1.0 ZIP from the release commit/tag.
+1. Complete release validation and build the final v1.2.0 ZIP from the release commit/tag.
 2. Open the OpenAI Plugins publisher dashboard:
    `https://platform.openai.com/plugins`
-3. Upload `orbit-thread-plugin-1.1.0.zip`.
+3. Upload `orbit-thread-plugin-1.2.0.zip`.
 4. Complete automated checks and resolve genuine findings.
 5. Review listing metadata and required policy/data-handling declarations.
 6. Choose **Submit for review**.
@@ -63,7 +63,7 @@ claude plugin validate ./plugin --strict
 claude plugin validate . --strict
 ```
 
-Then use the directory management/submission surface in Claude, connect the GitHub account that owns `shab1h-gh/orbit-thread`, select the repository/plugin, complete the listing details and submit it for review. Use the immutable v1.1.0 release/tag once created.
+Then use the directory management/submission surface in Claude, connect the GitHub account that owns `shab1h-gh/orbit-thread`, select the repository/plugin, complete the listing details and submit it for review. Use the immutable v1.2.0 release/tag once created.
 
 A successful GitHub marketplace installation does not mean the plugin is approved for Anthropic's public directory.
 

package/docs/VALIDATION.md

@@ -177,3 +177,63 @@ Those native CLIs are not part of GitHub CI, so CI success does not claim those
 
 OpenAI and Anthropic public-directory review is separate from npm/GitHub distribution. Their publisher dashboards are authoritative after submission; local validation does not imply approval.
 
+## Orbit Resume v1.2.0 validation
+
+Release validation completed on 12 October 2026 on the `feature/orbit-resume` branch (PR #3) for v1.2.0. `orbit-thread@1.1.0` was confirmed published on the public npm registry before the version bump; v1.2.0 has not been tagged, published or merged.
+
+### Verified locally for the v1.2.0 release candidate
+
+- All 43 automated tests passed, including Codex and Claude project installation,
+  reinstall, update, Doctor, missing/invalid/stale handoffs, branch changes,
+  future dates, terminal-control sanitisation, secret redaction, and preservation
+  of dirty working trees.
+- `npm run validate`, `npm run scan:public`, `npm run build:plugin` and
+  `git diff --check` passed.
+- `claude plugin validate ./plugin --strict` and `claude plugin validate . --strict` passed.
+- `npm pack` produced `orbit-thread-1.2.0.tgz` (28 files, including `lib/resume.mjs` and
+  `plugin/skills/orbit-resume/`), and `npm run smoke:pack` passed against it in a disposable
+  Git project: `resume`, install, setup, configure, Doctor, update and uninstall.
+- `dist/orbit-thread-plugin-1.2.0.zip` contains 16 files: portable and Claude manifests,
+  all three skills, icon, licence, privacy and security documents. Both archives report
+  version 1.2.0 throughout, with no private paths or build residue.
+- Release metadata (`package.json`, `plugin/plugin.json`, `plugin/.claude-plugin/plugin.json`
+  and `.claude-plugin/marketplace.json`) is consistent at 1.2.0; `npm run validate` enforces this.
+
+### Compatibility with v1.1.0 installations
+
+Using the published `orbit-thread@1.1.0` from the npm registry, a disposable project was installed
+and set up with `handoff` and `orbit-setup` only, then updated with the packed 1.2.0 CLI.
+Update added `orbit-resume` for Codex and Claude, kept the existing `handoff` and `orbit-setup`
+skills, `.orbit-thread/config.json`, local edits to living docs and user content in `AGENTS.md`, and
+Doctor reported all three skills current at v1.2.0. A locally edited managed skill file was still
+refused with an instruction to preserve changes. The 1.2.0 `resume` command ran read-only,
+and uninstall preserved project docs and configuration.
+
+### Reported native agent testing (not CI)
+
+The maintainer reported successful authenticated native testing of the feature-branch skills in fresh
+Codex and Claude Code sessions, using a disposable Git project: Setup, Doctor, handoff
+validation and Resume recovery scenarios passed, and both automatic and explicit manual Resume
+invocation worked in each agent. This was an interactive local test recorded from the
+maintainer's report; it is not part of GitHub CI and was not re-run during release preparation.
+Codex emitted macOS temporary-cache warnings during Git reads but still reported branch,
+status and commit.
+
+### Verified in GitHub CI
+
+GitHub CI covers the macOS and Linux Node.js matrix, the test suite, package validation, the
+public-source scan, plugin ZIP generation, `npm pack` and the packed-tarball smoke test. CI does not run
+authenticated Codex or Claude sessions or `claude plugin validate`. The PR #3 CI run on the
+previous commit passed; CI for the release commit is checked on the pull request after push.
+
+### Security review
+
+A security review identified a low-risk terminal-control injection through branch metadata in a
+local handoff. Resume strips terminal control sequences from displayed repository and handoff text; a
+regression test confirms they do not reach terminal output.
+
+### Remaining release-gate checks
+
+- Merge PR #3, then tag v1.2.0 from the merged release commit.
+- Publish `orbit-thread@1.2.0` and repeat the public-registry smoke test described in
+  [PUBLISHING.md](PUBLISHING.md).

package/lib/cli.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { setupProject, checkProject, removeProjectConfig, resolveProjectRoot } from '../plugin/skills/orbit-setup/scripts/setup_project.mjs';
 import { configureProject, readProjectConfig } from '../plugin/skills/orbit-setup/scripts/project_config.mjs';
+import { resumeProject } from './resume.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
@@ -13,7 +14,7 @@ const skillsRoot = path.join(packageRoot, 'plugin/skills');
 const marker = '.orbit-thread.json';
 const legacyMarker = '.orbit-handoff.json';
 const agents = ['codex', 'claude'];
-const skills = ['handoff', 'orbit-setup'];
+const skills = ['handoff', 'orbit-setup', 'orbit-resume'];
 const digest = data => crypto.createHash('sha256').update(data).digest('hex');
 const exists = p => { try { fs.lstatSync(p); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
 
@@ -143,6 +144,7 @@ Usage: orbit-thread <command> [options]
 Commands:
   install       Install the Orbit Thread skills.
   setup         Prepare/upgrade the current project workflow and living docs.
+  resume        Show concise project continuity and current Git state (read-only).
   configure     Set project subagent preferences.
   doctor        Check installed skills and project continuity health.
   update        Upgrade unchanged managed skill files to this package version.
@@ -204,7 +206,7 @@ export async function main(argv) {
 
   let [command, ...rest] = argv;
   if (command === 'init') command = 'setup';
-  if (!['install', 'setup', 'configure', 'check', 'doctor', 'update', 'uninstall'].includes(command)) throw new Error(`Unknown command: ${command}`);
+  if (!['install', 'setup', 'resume', 'configure', 'check', 'doctor', 'update', 'uninstall'].includes(command)) throw new Error(`Unknown command: ${command}`);
 
   const options = parseOptions(rest);
   const scope = options.scope ?? 'project';
@@ -215,6 +217,12 @@ export async function main(argv) {
   let selected = selectedAgents(options.agent);
   const root = resolveProjectRoot(process.cwd());
 
+  if (command === 'resume') {
+    if (rest.length) throw new Error('resume does not accept options');
+    resumeProject(root);
+    return;
+  }
+
   if (command === 'configure') {
     if (options.show) { console.log(JSON.stringify(readProjectConfig(root), null, 2)); return; }
     if ((options.model !== undefined || options.reasoning !== undefined) && selected.length !== 1) {

package/lib/resume.mjs

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const handoffPath = root => path.join(root, 'HANDOFF-STATE.md');
+const secret = /\b(api[_ -]?key|access[_ -]?token|refresh[_ -]?token|password|secret|authorization|bearer)\b\s*[:=]\s*[^\s,;]+/gi;
+
+function scrub(value) {
+  const safe = value.slice(0, 500)
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/\u009b[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '');
+  if (/\b(?:password|passphrase|token|secret|credential|private\s+key|api[_ -]?key|authorization|bearer)\b/i.test(safe)) {
+    return '[redacted sensitive-looking handoff line]';
+  }
+  return safe.replace(secret, '$1=[redacted]');
+}
+
+function readHandoff(root) {
+  const file = handoffPath(root);
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return { state: 'invalid', reason: 'not a regular local file' };
+    if (stat.size > 32768) return { state: 'invalid', reason: 'larger than the 32 KB safety limit' };
+    const text = fs.readFileSync(file, 'utf8');
+    const lines = text.split(/\r?\n/);
+    if (lines.length > 51) return { state: 'invalid', reason: 'over the 50-line limit' };
+    if (!/^# Handoff State\s*$/m.test(text)) return { state: 'invalid', reason: 'missing the Handoff State heading' };
+    const updated = text.match(/^Updated:\s*(\d{2})-(\d{2})-(\d{4})(?:\s+\d{2}:\d{2})?\s*$/m);
+    const objective = section(text, 'Current objective');
+    if (!updated || !objective.length) return { state: 'invalid', reason: 'missing a valid update date or current objective' };
+    const date = new Date(Number(updated[3]), Number(updated[2]) - 1, Number(updated[1]));
+    if (Number.isNaN(date.valueOf()) || date.getDate() !== Number(updated[1]) || date.getMonth() !== Number(updated[2]) - 1) {
+      return { state: 'invalid', reason: 'invalid update date' };
+    }
+    return {
+      state: 'valid', text, updated: `${updated[3]}-${updated[2]}-${updated[1]}`,
+      fields: {
+        objective,
+        completed: section(text, 'Completed milestones'),
+        unfinished: section(text, 'In progress'),
+        risks: section(text, 'Open issues / risks'),
+        verification: section(text, 'Verification'),
+        next: section(text, 'Immediate next steps'),
+      },
+    };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'missing' };
+    throw error;
+  }
+}
+
+function section(text, title) {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = text.match(new RegExp(`^##\\s+${escaped}\\s*\\r?\\n([\\s\\S]*?)(?=^##\\s+|\\s*$)`, 'm'));
+  if (!match) return [];
+  return match[1].split(/\r?\n/).map(line => line.trim()).filter(line => line && !/^<!--/.test(line)).slice(0, 6).map(line => scrub(line));
+}
+
+function git(root, args) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).trim();
+  } catch { return null; }
+}
+
+function currentGit(root) {
+  const branch = git(root, ['symbolic-ref', '--short', '-q', 'HEAD']) ?? (git(root, ['rev-parse', '--short', 'HEAD']) ? 'detached HEAD' : null);
+  const status = git(root, ['status', '--short', '--untracked-files=normal']);
+  const commitDate = git(root, ['log', '-1', '--format=%cs']);
+  const changed = (status ?? '').split(/\r?\n/).filter(Boolean);
+  const safeChanged = changed.filter(line => !/(^|\s)(?:\.env(?:\.|\s|$)|\.dev\.vars(?:\s|$)|.*(?:secret|credential|private[_-]?key|id_rsa|id_ed25519|\.pem|\.key|\.netrc|\.npmrc|\.pypirc).*)/i.test(line));
+  return { branch, status, changed: safeChanged.slice(0, 8), count: changed.length, commitDate };
+}
+
+function relevantDocs(text, root) {
+  const topics = [
+    ['PRODUCT.md', /product|workflow|scope|user-facing|feature/i],
+    ['DESIGN.md', /ui|ux|design|layout|visual|accessibility/i],
+    ['ARCHITECTURE.md', /architecture|runtime|data flow|integration|database|storage|deploy/i],
+    ['SECURITY.md', /auth|security|permission|secret|tenant|trust|privacy/i],
+    ['ROADMAP.md', /roadmap|plan|milestone|later|defer/i],
+  ];
+  const matches = [];
+  for (const [name, pattern] of topics) {
+    if (!pattern.test(text)) continue;
+    for (const file of [path.join(root, name), path.join(root, 'docs', name)]) {
+      try {
+        if (fs.lstatSync(file).isFile() && !fs.lstatSync(file).isSymbolicLink()) { matches.push(path.relative(root, file)); break; }
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  }
+  return [...new Set(matches)].slice(0, 3);
+}
+
+function printLines(label, lines, fallback) {
+  console.log(`${label}:`);
+  if (!lines.length) console.log(`  ${fallback}`);
+  else lines.forEach(line => console.log(`  ${line}`));
+}
+
+export function resumeProject(root) {
+  root = path.resolve(root);
+  const handoff = readHandoff(root);
+  const gitState = currentGit(root);
+  let status = handoff.state;
+  let reason = handoff.reason;
+  const recordedBranch = handoff.state === 'valid' ? handoff.text.match(/^(?:current\s+)?branch:\s*([^\s]+)/im)?.[1] : null;
+  if (recordedBranch && gitState.branch) {
+    if (recordedBranch !== gitState.branch) { status = 'possibly outdated'; reason = `recorded branch ${recordedBranch} differs from current branch`; }
+  }
+  const today = new Date();
+  const todayDate = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}`;
+  if (handoff.state === 'valid' && handoff.updated && handoff.updated > todayDate) {
+    status = 'possibly outdated';
+    reason = 'handoff date is in the future';
+  }
+  if (handoff.state === 'valid' && gitState.commitDate && handoff.updated && gitState.commitDate > handoff.updated) {
+    status = 'possibly outdated';
+    reason = `Git has a commit dated ${gitState.commitDate}, after the handoff date`;
+  }
+
+  console.log('Orbit Resume (read-only)');
+  console.log(`Project: ${scrub(path.basename(root))}`);
+  console.log(`Handoff: ${status}${reason ? ` — ${scrub(reason)}` : ''}`);
+  if (handoff.state === 'valid') {
+    const usable = status === 'valid';
+    printLines('Objective', usable ? handoff.fields.objective : [], usable ? 'Not recorded.' : 'Treat the handoff as a lead; current repository evidence takes precedence.');
+    printLines('Completed milestones', usable ? handoff.fields.completed : [], 'No verified milestones recorded.');
+    printLines('Unfinished work', usable ? handoff.fields.unfinished : [], 'No in-progress work recorded.');
+    printLines('Risks', usable ? handoff.fields.risks : [], 'No risks recorded.');
+    printLines('Verification', usable ? handoff.fields.verification : [], 'No verification recorded.');
+  } else {
+    printLines('Objective', [], 'Unknown; do not infer it from an absent or invalid handoff.');
+    printLines('Completed milestones', [], 'No reliable handoff evidence.');
+    printLines('Unfinished work', [], 'Check the current task and Git changes before proceeding.');
+    printLines('Risks', [], handoff.state === 'invalid' ? 'Handoff was not used because it is invalid.' : 'No handoff exists yet.');
+    printLines('Verification', [], 'No reliable handoff evidence.');
+  }
+
+  console.log('Git status:');
+  if (!gitState.branch && gitState.status === null) console.log('  Git repository unavailable.');
+  else {
+    console.log(`  Branch: ${scrub(gitState.branch ?? 'unknown')}`);
+    console.log(`  Working tree: ${gitState.count ? `dirty (${gitState.count} change${gitState.count === 1 ? '' : 's'})` : 'clean'}`);
+    gitState.changed.forEach(line => console.log(`  ${scrub(line)}`));
+    if (gitState.count > gitState.changed.length) console.log(`  ${gitState.count - gitState.changed.length} sensitive-looking path(s) omitted.`);
+  }
+
+  const trustedNext = handoff.state === 'valid' && status === 'valid' ? handoff.fields.next : [];
+  const docs = relevantDocs([...(trustedNext.length ? trustedNext : []), ...(handoff.state === 'valid' ? handoff.fields.objective : [])].join(' '), root);
+  printLines('Next steps', trustedNext, handoff.state === 'valid' && status === 'valid' ? 'No next step recorded; inspect current changes and choose one from repository evidence.' : 'Inspect current Git changes, then identify the next action from the user request and tracked project docs.');
+  printLines('Relevant living docs', docs, 'None identified from the handoff; load a living doc only if the next action needs it.');
+  console.log('Keep unfinished working changes. Do not reset or clean the repository. Current Git and tracked docs override stale handoff details.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbit-thread",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Token-efficient project setup, checkpoints and coding-session continuity for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   "repository": { "type": "git", "url": "git+https://github.com/shab1h-gh/orbit-thread.git" },
   "homepage": "https://github.com/shab1h-gh/orbit-thread#readme",
   "bugs": { "url": "https://github.com/shab1h-gh/orbit-thread/issues" },
-  "keywords": ["codex", "claude-code", "agent-skills", "continuity", "project-setup", "handoff", "context-efficiency"],
+  "keywords": ["codex", "claude-code", "agent-skills", "continuity", "project-setup", "handoff", "resume", "context-efficiency"],
   "files": ["bin/", "lib/", "plugin/", "docs/", "README.md", "LICENSE", "SECURITY.md", "PRIVACY.md", "CONTRIBUTING.md", "CHANGELOG.md"],
   "scripts": {
     "test": "node --test",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "orbit-thread",
   "displayName": "Orbit Thread",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Token-efficient project setup, checkpoints and coding-session continuity.",
   "author": { "name": "Shabih Anwar", "url": "https://github.com/shab1h-gh" },
   "homepage": "https://github.com/shab1h-gh/orbit-thread",
@@ -11,6 +11,6 @@
   "documentationUrl": "https://github.com/shab1h-gh/orbit-thread#readme",
   "supportUrl": "https://github.com/shab1h-gh/orbit-thread/issues",
   "privacyPolicyUrl": "https://github.com/shab1h-gh/orbit-thread/blob/main/PRIVACY.md",
-  "keywords": ["continuity", "handoff", "project-setup", "developer-tools"],
+  "keywords": ["continuity", "handoff", "resume", "project-setup", "developer-tools"],
   "skills": "./skills/"
 }

package/plugin/README.md

@@ -1,25 +1,27 @@
 # Orbit Thread
 
-Orbit Thread provides two local coding skills:
+Orbit Thread provides three local coding skills:
 
 - **Orbit Setup** prepares a project with lightweight living docs, selective context rules and configurable subagent preferences.
 - **Handoff** overwrites a compact, evidence-only `HANDOFF-STATE.md` so a fresh coding session can resume from Git + current project truth rather than a large old conversation.
+- **Resume** reconstructs concise project context from the latest usable handoff, current Git state and task-relevant living docs.
 
 Standalone commands:
 
-- Codex: `$orbit-setup` and `$handoff`
-- Claude Code: `/orbit-setup` and `/handoff`
+- Codex: `$orbit-setup`, `$handoff` and `$orbit-resume`
+- Claude Code: `/orbit-setup`, `/handoff` and `/orbit-resume`
 
 Claude plugin commands:
 
 - `/orbit-thread:orbit-setup`
 - `/orbit-thread:handoff`
+- `/orbit-thread:orbit-resume`
 
 Setup creates only missing PRODUCT, DESIGN, ARCHITECTURE, SECURITY and ROADMAP templates, preserves existing equivalents, manages a concise Orbit Thread section in AGENTS.md/CLAUDE.md, and keeps local handoff/tool state Git-ignored.
 
-The project rules update living docs in place, load only relevant context, default to no subagents with a maximum of two, and request Handoff after meaningful verified milestones/completed coding tasks.
+Start each coding task in a fresh chat and run Resume once at session start, automatically where supported or manually as a fallback. The project rules update living docs in place, load only relevant context, default to no subagents with a maximum of two, and request Handoff after meaningful verified milestones/completed coding tasks.
 
-Handoff is overwrite-only, capped at 50 lines, secret-checked before atomic replacement and makes no network calls or Git mutations.
+Handoff is overwrite-only, capped at 50 lines, secret-checked before atomic replacement and makes no network calls or Git mutations. Resume and `npx orbit-thread resume` are read-only and preserve unfinished work.
 
 There is no MCP server, telemetry or external account.
 

package/plugin/plugin.json

@@ -1,26 +1,26 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "orbit-thread",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Token-efficient project setup, checkpoints and coding-session continuity.",
   "author": { "name": "Shabih Anwar", "url": "https://github.com/shab1h-gh" },
   "homepage": "https://github.com/shab1h-gh/orbit-thread",
   "repository": "https://github.com/shab1h-gh/orbit-thread",
   "license": "MIT",
-  "keywords": ["handoff", "codex", "claude-code", "continuity", "project-setup", "developer-tools"],
+  "keywords": ["handoff", "resume", "codex", "claude-code", "continuity", "project-setup", "developer-tools"],
   "extensions": {
     "com.openai": {
       "interface": {
         "displayName": "Orbit Thread",
         "shortDescription": "Lean coding continuity",
-        "longDescription": "Orbit Thread gives coding agents a small, durable continuity layer. Orbit Setup creates only missing PRODUCT, DESIGN, ARCHITECTURE, SECURITY and ROADMAP living docs, adds selective context-loading and bounded-subagent rules, and keeps local execution state separate from tracked project truth. Handoff then overwrites a compact HANDOFF-STATE.md at meaningful verified checkpoints and completed coding tasks so a fresh session can resume from Git, current docs and the exact next action instead of carrying a large chat history. Handoffs are capped at 50 lines, validated before atomic replacement, and the writer makes no network calls or Git mutations. Existing project docs and unrelated instructions are preserved.",
+        "longDescription": "Orbit Thread gives coding agents a small, durable continuity layer. Orbit Setup creates only missing PRODUCT, DESIGN, ARCHITECTURE, SECURITY and ROADMAP living docs, adds selective context-loading and bounded-subagent rules, and keeps local execution state separate from tracked project truth. Handoff overwrites a compact HANDOFF-STATE.md at verified checkpoints. Resume starts a fresh chat from the current handoff, read-only Git state and only the living docs needed for the task, reducing repeated context while preserving unfinished changes. Handoffs are capped at 50 lines, validated before atomic replacement, and the writer makes no network calls or Git mutations. Existing project docs and unrelated instructions are preserved.",
         "developerName": "Shabih Anwar",
         "category": "Developer Tools",
-        "capabilities": ["Prepare project continuity", "Save verified coding checkpoints"],
+        "capabilities": ["Prepare project continuity", "Save verified coding checkpoints", "Resume coding sessions"],
         "websiteURL": "https://github.com/shab1h-gh/orbit-thread",
         "supportURL": "https://github.com/shab1h-gh/orbit-thread/issues",
         "privacyPolicyURL": "https://github.com/shab1h-gh/orbit-thread/blob/main/PRIVACY.md",
-        "defaultPrompt": ["Prepare this coding project for efficient continuity, or save verified current state at a meaningful checkpoint."],
+        "defaultPrompt": ["Prepare this coding project for efficient continuity, resume a fresh coding session, or save verified current state at a meaningful checkpoint."],
         "brandColor": "#4338CA",
         "composerIcon": "./assets/icon.png",
         "logo": "./assets/icon.png"

package/plugin/skills/handoff/SKILL.md

@@ -41,6 +41,7 @@ Omit empty sections. Aim for about 30 lines; hard cap 50. State each fact once.
 - Evidence only. Never claim a test, deployment, commit, push or external action happened without evidence.
 - Never include secrets, credentials, tokens, private keys, recovery codes, `.env`/`.dev.vars` values, personal data or sensitive production data.
 - Do not record the current HEAD SHA; it becomes stale easily. Exact SHAs are allowed only for immutable earlier revisions such as releases, deployments or rollback points.
+- When Git is available, record the current branch as `Branch: <name>` under `Current state` so a later Resume can detect a branch change. Never record the current HEAD SHA.
 - `HANDOFF-STATE.md` is local current state, intended to be Git-ignored. Never append history or make committing it a next step.
 - Durable product, design, architecture, security or roadmap truth belongs in tracked living docs. Handoff does not replace those files.
 - At an intermediate checkpoint, do not stop merely because the handoff was written.

package/plugin/skills/orbit-resume/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: orbit-resume
+description: Recover essential project context at the start of a fresh Codex or Claude Code conversation from the latest usable handoff, current Git state and only the living docs needed for the current task. Use once per new coding session, or when the user explicitly asks to resume project work.
+---
+
+# Orbit Thread Resume
+
+Recover the current project state once at the beginning of a fresh coding conversation. Keep the context small and preserve unfinished changes.
+
+## Workflow
+
+1. If the user already supplied output from `npx orbit-thread resume` in this conversation, use it. Otherwise inspect `HANDOFF-STATE.md` once if it exists, then run read-only `git status --short --branch`, `git diff --stat HEAD`, and `git log -1 --oneline` from the project root. Do not invoke npm, install tools, or search the repository broadly.
+2. Treat the handoff as a lead. Current Git state and tracked project docs override stale or conflicting handoff details. A missing or malformed handoff is not a reason to invent the objective or completed work; use the user's current request and state what remains unknown.
+3. Preserve all dirty and untracked work. Never reset, clean, stash, stage, commit, checkout, deploy, or otherwise change repository state.
+4. Read only the living doc that directly informs the current requested task: PRODUCT for scope or behaviour, DESIGN for UI, ARCHITECTURE for runtime/data flow, SECURITY for trust/auth/secrets, ROADMAP for planning. Use its existing root or `docs/` location. Do not load unrelated docs or repeat facts already clear from the handoff.
+5. Give the user a compact summary of the objective, verified milestones, unfinished work, risks, verification, Git state, and immediate next action. Separate facts from unknowns. End with one clear next action grounded in the current request and repository evidence.
+
+Run this skill once per fresh conversation. Do not repeat it during the same session unless the user asks for a fresh recovery. If the host cannot invoke it automatically, the reliable fallback is `$orbit-resume` in Codex, `/orbit-resume` in Claude Code, or `/orbit-thread:orbit-resume` from the Claude marketplace plugin.
+
+## Safety
+
+- Read only the handoff, Git summaries, and task-relevant living docs. Never read `.env`, `.dev.vars`, credentials, private keys, or unrelated files.
+- Do not echo secret-looking values or sensitive local file paths. Keep the user's unfinished work intact.
+- The `npx orbit-thread resume` CLI command is read-only and can be run by the developer for a concise terminal summary. Do not run `npx` from this skill because it can download packages when the CLI is unavailable.
+- Do not claim a check, test, deployment, commit, or external action unless current evidence confirms it.

package/plugin/skills/orbit-resume/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Orbit Thread Resume"
+  short_description: "Recover concise project context"
+  default_prompt: "Use $orbit-resume once to recover the verified project state and next action for this fresh coding session."
+policy:
+  allow_implicit_invocation: true

package/plugin/skills/orbit-setup/scripts/setup_project.mjs

@@ -28,8 +28,9 @@ const agentsBlock = config => `${begin}
 - Inspect only source files needed for the task. Do not broadly scan generated, vendor, dependency, build, coverage or cache directories, and do not reread unchanged context without a reason.
 - Living docs describe CURRENT truth. After verified work changes that truth, update affected existing sections in place during the same milestone. Never append session diaries or duplicate superseded sections; Git is history. Never rewrite an applied migration.
 - Run the smallest relevant verification before claiming a milestone or task complete. Never claim a test, deployment, commit, push or external action that did not run.
+- Start each new coding task in a fresh chat and invoke \`$orbit-resume\` once at session start. Do this automatically where the host supports it; otherwise the reliable fallback is to invoke it manually. Do not repeat Resume in the same session unless the user asks for a fresh recovery.
 - Run the installed \`handoff\` skill after a meaningful verified milestone that changed repository state or durable project truth, and after each completed coding task with such changes before the final reply. Also checkpoint before \`/clear\`, session end, or a usage/context stop when warning is available. Skip read-only questions and trivial edits. Intermediate checkpoints must not stop unfinished work.
-- Each checkpoint overwrites \`HANDOFF-STATE.md\`. After a fresh/cleared/recovered session: read the handoff once if present, inspect branch/status/diff/recent log, read only relevant living docs, then inspect only source needed for the exact next action. Do not reconstruct old conversation history or repeat completed work.
+- Each checkpoint overwrites \`HANDOFF-STATE.md\`. Resume reads the handoff once if present, checks current Git state, then reads only task-relevant living docs and source. Do not reconstruct old conversation history or repeat completed work.
 ${renderSubagentBlock(config)}
 - Read-only Git inspection is allowed. Commit, push, merge, rebase, reset, branch deletion or other Git writes require explicit authority in the current request. Never force-push or destructively clean without explicit authority.
 - Never place secrets, credentials, environment values, private keys, recovery codes, personal data or sensitive production data in living docs or \`HANDOFF-STATE.md\`.
@@ -39,7 +40,7 @@ ${end}
 const claudeBlock = `${begin}
 ## Orbit Thread
 
-Read and follow \`AGENTS.md\` for project workflow, selective context loading, subagents and checkpoints. On a fresh or recovered session, resume from \`HANDOFF-STATE.md\` + current Git state + only the relevant living docs instead of reconstructing old conversation history.
+Read and follow \`AGENTS.md\` for project workflow, selective context loading, subagents and checkpoints. Start each new coding task in a fresh chat and invoke \`/orbit-resume\` once at session start, automatically where supported. If automatic invocation is unavailable, manually run \`/orbit-resume\` (or \`/orbit-thread:orbit-resume\` from the marketplace plugin). Do not repeat Resume in the same session unless the user asks for a fresh recovery.
 ${end}
 `;
 const templates = {