orbit-thread 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.2.2 — 12 October 2026
+
+- Add a public [Terms of Service](TERMS.md) and declare it as `termsOfServiceURL` in the OpenAI plugin manifest.
+- Replace the single long conversation starter with three short ones (each under 128 characters) covering Setup, Handoff and Resume.
+- Correct the stale `publication.release_notes` text in the OpenAI manifest, which still described v1.1.
+- Ship `TERMS.md` in the npm package and the plugin ZIP, and make `npm run validate` check the Terms URL and conversation-starter limits.
+- Documentation and metadata release only: no change to Setup, Handoff or Resume behaviour, the handoff format, installer logic or the three canonical skills. Existing installations keep working; `orbit-thread update` refreshes the version.
+
 ## 1.2.1 — 12 October 2026
 
 - Fix Orbit Resume reporting "No verified milestones recorded" for valid handoffs that use `## Completed this session`. Resume now reads both headings.

package/README.md

@@ -1,26 +1,28 @@
-# 🧵 Orbit Thread
+<h1 align="center">🧵 Orbit Thread</h1>
+<p align="center"><strong>Pick up where you left off. Not where the chat ended.</strong></p>
+<p align="center">Lightweight project context, verified handoffs and fresh-session recovery for <strong>Codex</strong> and <strong>Claude Code</strong>.</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/orbit-thread"><img alt="npm version" src="https://img.shields.io/npm/v/orbit-thread?label=npm"></a>
+  <a href="https://github.com/shab1h-gh/orbit-thread/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/shab1h-gh/orbit-thread/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-blue.svg"></a>
+</p>
+<p align="center"><a href="#quick-start"><strong>Quick start</strong></a> · <a href="#how-it-works">How it works</a> · <a href="#orbit-resume-starting-a-fresh-session">Orbit Resume</a> · <a href="#command-reference">Commands</a> · <a href="#troubleshooting">Troubleshooting</a></p>
 
-**Pick up where you left off, without carrying an entire coding conversation into the next session.**
+---
 
-[![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 prepares small living docs, captures meaningful progress and helps your next coding session recover only the context it needs. **Your repository and Git remain the source of truth.** There is no hosted memory account or giant session diary.
 
-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.
+### Three skills, one workflow
 
-No giant session diary. No separate account or hosted memory service. Your repository and Git history remain the source of truth.
-
-| 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)
+| Skill | What it does | When to use it |
+| :--- | :--- | :--- |
+| 🧭 **[Orbit Setup](#what-setup-creates)** | Prepares project docs, agent instructions and subagent preferences without replacing existing knowledge. | Starting or onboarding a project. |
+| 💾 **[Handoff](#when-to-save-a-handoff)** | Writes a concise, verified checkpoint to `HANDOFF-STATE.md`. | After meaningful milestones or before a fresh chat. |
+| ▶️ **[Orbit Resume](#orbit-resume-starting-a-fresh-session)** | Recovers progress, open tasks and the next action from the handoff and read-only repository evidence. | Once at the start of a new coding conversation. |
 
 ## Quick start
 
-> 🚀 Run these commands **inside the project** you want to set up.
+> **Run these commands from the project root.** Requires Node.js 20+ on macOS or Linux.
 
 ```bash
 npx orbit-thread install
@@ -42,41 +44,29 @@ Once installed, call the skills in your coding agent:
 | 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.
+The commands in the table are **skill invocations in your coding agent's chat**, not Terminal commands. The agent can also save a handoff after a verified milestone, where its host supports automatic skill invocation.
 
 ## How it works
 
-Orbit Thread keeps **lasting project knowledge** separate from **what the agent is doing right now**.
+Orbit Thread keeps **lasting project knowledge** separate from **the task you're 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
+```mermaid
+flowchart LR
+    A["🧭 Setup<br/>Docs + agent rules"] --> B["Build and verify<br/>Real project work"]
+    B --> C["💾 Handoff<br/>Local checkpoint"]
+    C --> D["▶️ Resume<br/>Fresh chat + Git state"]
+    D --> B
 ```
 
-The important distinction:
-
-- **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.
+| Source | Role |
+| :--- | :--- |
+| **Git** | Code history, active branch and working-tree truth. |
+| **Living docs** | The current product, design, architecture, security and roadmap. |
+| **`HANDOFF-STATE.md`** | Short local checkpoint of verified progress and unfinished work. |
+| **Resume** | Reconciles that checkpoint with current Git and only the relevant docs. |
 
-The handoff is a checkpoint, **not** another changelog or a substitute for Git. If the handoff is stale, the current repository state wins.
+> [!IMPORTANT]
+> A handoff isn't a changelog or synchronised chat history. **Current repository evidence overrides stale notes.**
 
 ## What setup creates
 
@@ -116,25 +106,19 @@ They also tell agents to preserve applied migrations, leave history to Git and r
 
 ### When to save a handoff
 
-Handoff is intended for moments that matter:
-
-- 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.
-
-It is not necessary for ordinary questions or tiny edits with no lasting effect. Each successful checkpoint **replaces** the previous handoff.
+Save a Handoff **after verified work**, before clearing a chat or when nearing a context/usage limit. It is useful after a meaningful milestone or a completed coding task, not for every question or trivial edit. Each checkpoint **overwrites** the previous one.
 
 ### What gets saved?
 
-Handoffs are usually around 30 lines, with a **hard limit of 50 lines**.
+The local, Git-ignored `HANDOFF-STATE.md` records a compact checkpoint, usually about 30 lines, with a **50-line maximum**:
 
 ```markdown
 # Handoff State
 
-Updated: 07-10-2026 00:30
+Updated: 12-10-2026 08:30
 
 ## Current objective
-- Finish account security settings.
+- Complete account security settings.
 
 ## Completed milestones
 - Added the settings route.
@@ -143,8 +127,11 @@ Updated: 07-10-2026 00:30
 ## In progress
 - Passkey management UI.
 
+## Current state
+- Branch: feature/security-settings
+
 ## Open issues / risks
-- Passkey removal still needs a browser test.
+- Passkey removal needs browser verification.
 
 ## Immediate next steps
 1. Finish passkey management.
@@ -155,31 +142,70 @@ Updated: 07-10-2026 00:30
 - Unit tests passed: 42/42.
 ```
 
-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.
+**v1.2.1 compatibility:** Resume also recognises `## Completed this session`, while keeping `## Completed milestones` canonical. If both have entries, it uses the canonical heading without duplicates. It handles **multiple entries, blank lines and subheadings**, showing up to six entries per section to keep the summary compact.
+
+Handoff validates the replacement, checks recognisable secret patterns and writes atomically. It makes no network requests or Git changes. Never put credentials or sensitive personal/production details in a handoff.
+
+### Orbit Resume: starting a fresh session
+
+**Orbit Resume turns a previous checkpoint into an evidence-based starting point for a new chat.** It reads the latest usable handoff, current Git status and only the living docs relevant to the next task. You don't need to paste your old conversation into the new one.
 
-### Starting a fresh session
+After Setup, your project instructions ask the agent to run Resume **once at the start of a fresh coding session**. Automatic invocation varies by host; the reliable fallback is a manual skill call:
 
-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.
+| Where | Type in the **agent chat** |
+| :--- | :--- |
+| **Codex** | `$orbit-resume` |
+| **Claude Code** | `/orbit-resume` |
+| **Claude GitHub marketplace plugin** | `/orbit-thread:orbit-resume` |
 
-For a terminal summary, run:
+**Terminal-only summary:** run this from your project's root:
 
 ```bash
-npx orbit-thread resume
+npx orbit-thread@latest resume
 ```
 
-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.
+That CLI command is read-only and **does not launch a coding agent**. Running `npx` may fetch the package from npm if needed; the Resume **skill itself never runs `npx` or installs tools**. Don't rerun the skill repeatedly in the same conversation.
 
-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.
+#### What Resume recovers
 
-The project instructions ask the agent to:
+| Signal | What it tells you |
+| :--- | :--- |
+| **Objective and milestones** | Previously recorded goals and verified achievements, with explicit unknowns where evidence is missing. |
+| **Unfinished work** | In-progress tasks, risks, verification notes and recorded next actions. |
+| **Current Git state** | Branch and dirty/untracked changes, without modifying your work. |
+| **Relevant living docs** | Pointers to `PRODUCT.md`, `DESIGN.md`, `ARCHITECTURE.md`, `SECURITY.md` or `ROADMAP.md` when the task needs them. |
 
-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.
+Missing, invalid or **possibly outdated** handoffs are reported instead of trusted blindly. A changed branch, a handoff date in the future or a newer Git commit date may flag a checkpoint as outdated. Current Git and tracked docs take priority; Resume never invents missing objectives or verification.
 
-You do not need to paste an old conversation into the next session.
+#### Common Resume use cases
+
+| Situation | Recommended action |
+| :--- | :--- |
+| **Fresh chat after a long task** | Write `$handoff` or `/handoff` after verified progress, then Resume in the next chat. |
+| **Context or usage limit** | Checkpoint before the limit when possible, then restart a conversation in the same project. |
+| **Switching Codex ↔ Claude Code** | Install for both agents in the **same local repo**; either agent can Resume from the same checkpoint and Git state. |
+| **Returning after days away** | Resume, review any stale-branch or commit warning, then consult only current relevant docs. |
+| **Working tree has uncommitted edits** | Resume identifies current changes **without** reset, clean, stash, stage or commit. |
+| **No handoff yet / new clone** | Resume reports what's unknown; give the agent the current task and let it inspect relevant current files. |
+
+#### Example: carry on without your old conversation
+
+**1. Save a checkpoint.** After completing and verifying part of a feature, type `$handoff` in Codex or `/handoff` in Claude Code.
+
+**2. Start a fresh chat** in the same project. If Resume doesn't start automatically, type `$orbit-resume` or `/orbit-resume`.
+
+**3. Continue from the recovered context.** For example:
+
+> Continue the unfinished account settings feature. Preserve my uncommitted changes, check current Git state, and read only the files needed for the next step.
+
+#### Safety and limitations
+
+- **Read-only:** Resume does not modify files or Git, reset, clean, stash, stage, commit, checkout, deploy or push.
+- **Selective context:** The skill checks the handoff, Git summaries and task-relevant living docs; it doesn't read `.env`, `.dev.vars`, private keys or unrelated files.
+- **Conservative redaction:** Secret-looking values and paths are hidden. Benign lines mentioning `token` or `secret` may also be redacted.
+- **Bounded input/output:** Handoff is capped at 50 lines; the terminal CLI refuses symlinks, invalid dates and files larger than 32 KB.
+- **Local state:** `HANDOFF-STATE.md` is Git-ignored, so it doesn't automatically transfer to a different machine or clean clone.
+- **Evidence first:** Resume cannot recover facts nobody recorded or prove an unverified test passed. Current repository state overrides stale notes.
 
 ## Configure subagents
 
@@ -300,7 +326,7 @@ This GitHub marketplace route is separate from the **official Anthropic public d
 | --- | --- |
 | `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 resume` | Print a concise, read-only project and Git summary; takes no extra options. |
 | `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. |
@@ -342,6 +368,36 @@ If you installed the Claude GitHub marketplace plugin, update or reinstall it fr
 
 ## Troubleshooting
 
+
+<details>
+<summary><strong>Resume did not start automatically or the skill is missing</strong></summary>
+
+Automatic invocation depends on the coding host and its skill discovery. Use `$orbit-resume`, `/orbit-resume` or `/orbit-thread:orbit-resume` **in the agent chat**.
+
+If the skill is not found, verify the correct installation and scope:
+
+```bash
+npx orbit-thread doctor --agent both --scope project
+```
+
+You may need a fresh agent session to load new skills. A working `npx orbit-thread resume` Terminal command doesn't itself prove native skill discovery.
+
+</details>
+
+<details>
+<summary><strong>Resume reports a missing, invalid or outdated handoff</strong></summary>
+
+`HANDOFF-STATE.md` is local and Git-ignored; a fresh clone may not contain it. An invalid handoff might have a malformed date or heading, missing objective, excessive size or unsupported file type. An outdated warning may reflect a changed branch, future handoff date or newer Git commit. Check current repository evidence, preserve any unfinished work and save a new verified checkpoint when appropriate.
+
+</details>
+
+<details>
+<summary><strong>Resume missed a milestone or redacted harmless text</strong></summary>
+
+Use `## Completed milestones` for new checkpoints; v1.2.1 also reads `## Completed this session` and multiple entries per section. When both headings exist, the canonical one wins. Outdated handoffs are not accepted as verified progress. Privacy safeguards can redact an innocent sentence containing terms such as `secret` or `token`. Verify against the local handoff and Git without exposing sensitive data.
+
+</details>
+
 <details>
 <summary><strong>Doctor reports a changed AGENTS.md or CLAUDE.md block</strong></summary>
 
@@ -424,13 +480,13 @@ A restricted coding environment may report a permissions error even when your Ma
 
 > 🔒 Orbit Thread's handoff writer runs locally. It does not send files to an Orbit Thread service, collect telemetry or alter Git.
 
-The installer protects unmanaged skills and locally modified managed files. Setup leaves unrelated instructions and existing project documents alone.
+The installer protects unmanaged skills and locally modified managed files. Setup leaves unrelated instructions and existing project documents alone. Resume is read-only and conservatively redacts sensitive-looking text and paths in its report.
 
 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.
 
 Installing packages or using a coding agent can still involve **npm, GitHub, OpenAI or Anthropic** under those providers' own terms and privacy policies.
 
-Read [Security](SECURITY.md) and [Privacy](PRIVACY.md) for the details.
+Read [Security](SECURITY.md), [Privacy](PRIVACY.md) and [Terms of Service](TERMS.md) for the details.
 
 ## Provider directories
 

package/TERMS.md

@@ -0,0 +1,48 @@
+# Terms of Service
+
+**Effective date:** 12 October 2026  
+**Project:** Orbit Thread  
+**Maintainer:** Shabih Anwar
+
+## 1. About Orbit Thread
+
+Orbit Thread is a free, open-source, local-first developer tool for preparing project documentation, recording verified coding checkpoints, and recovering useful context in new Codex or Claude Code sessions. It is distributed through its [GitHub repository](https://github.com/shab1h-gh/orbit-thread), npm and supported plugin marketplaces.
+
+Orbit Thread does not provide a hosted account, cloud storage, remote memory service, or service-level availability commitment. Use of the software is subject to the open-source licence described below.
+
+## 2. Open-source licence
+
+Orbit Thread's source code is distributed under the [MIT Licence](LICENSE). The MIT Licence governs your rights to use, copy, modify and distribute the software, including its warranty and liability provisions. These terms describe the project and its operation; they do **not** replace or restrict rights granted by the MIT Licence.
+
+## 3. Your projects and responsibilities
+
+You remain responsible for your own repositories, code, files, project decisions, and use of coding agents. In particular:
+
+- Review proposed code, file changes and generated documentation before relying on them.
+- Verify important tests, security decisions, deployments and other actions independently.
+- Keep suitable backups and follow your organisation's policies when using Orbit Thread with shared or confidential projects.
+- Do not put passwords, API keys, recovery codes, personal data or other sensitive information into handoffs or living project documents.
+
+Orbit Thread includes safeguards for common secret patterns and accidental overwrites, but no automated check can guarantee that all sensitive material or mistakes will be detected.
+
+## 4. Local processing and third-party services
+
+Orbit Thread's local scripts operate on files in your project. Orbit Thread does not operate its own data-collection service or collect telemetry. The local handoff file is designed to be ignored by Git, but you are responsible for checking what your repository or coding agent actually shares.
+
+Installing Orbit Thread, using Git hosting, or invoking Codex, Claude Code and plugin marketplaces may involve **npm, GitHub, OpenAI, Anthropic or other providers**. Their separate terms, permissions, billing arrangements and privacy practices apply to those services. Orbit Thread does not control how third-party coding agents process information you choose to provide.
+
+For details, see the [Privacy Policy](PRIVACY.md) and [Security Policy](SECURITY.md).
+
+## 5. Software availability and limitations
+
+Orbit Thread is provided **"as is"**, without warranties, as described in the MIT Licence. There is no guarantee of uninterrupted availability, compatibility with every environment, particular token savings, perfect recovery of previous context, or detection of every error.
+
+A handoff is a compact checkpoint, not a complete conversation archive or a substitute for the current repository state. Resume may report missing or outdated information; it cannot verify work that was never recorded.
+
+## 6. Updates to these terms
+
+These terms may be revised when the project or its distribution changes. The effective date above will be updated for material revisions, and prior versions remain available in the public Git history.
+
+## 7. Support and contact
+
+For general questions and support, use [GitHub Issues](https://github.com/shab1h-gh/orbit-thread/issues). For security vulnerabilities, use [private GitHub security reporting](https://github.com/shab1h-gh/orbit-thread/security/advisories/new) rather than posting sensitive information publicly.

package/docs/PUBLISHING.md

@@ -1,10 +1,10 @@
 # npm publication and releases
 
-Orbit Thread v1.2.1 is a compatibility patch for Orbit Resume (v1.2.0 added Resume to the Orbit Thread line, which succeeded Orbit Handoff v1.0.x in v1.1.0).
+Orbit Thread v1.2.2 is a documentation and metadata release that resolves OpenAI plugin submission findings (Terms of Service URL and conversation-starter length). It does not change skill behaviour. v1.2.1 was a compatibility patch for Orbit Resume; v1.2.0 added Resume, and the Orbit Thread line succeeded Orbit Handoff v1.0.x in v1.1.0.
 
-`orbit-thread@1.2.0` is already published. v1.2.1 is a new version.
+`orbit-thread@1.2.1` is already published. v1.2.2 is a new version.
 
-Historical `orbit-handoff@1.0.0`, `orbit-handoff@1.0.1`, `orbit-thread@1.1.0` and `orbit-thread@1.2.0` releases are immutable. Do not republish, unpublish or move their release tags.
+Historical `orbit-handoff@1.0.0`, `orbit-handoff@1.0.1`, `orbit-thread@1.1.0`, `orbit-thread@1.2.0` and `orbit-thread@1.2.1` releases are immutable. Do not republish, unpublish or move their release tags.
 
 The new primary package is:
 
@@ -35,11 +35,11 @@ claude plugin validate . --strict
 Inspect:
 
 ```text
-orbit-thread-1.2.1.tgz
-dist/orbit-thread-plugin-1.2.1.zip
+orbit-thread-1.2.2.tgz
+dist/orbit-thread-plugin-1.2.2.zip
 ```
 
-The npm tarball should contain 28 files (version 1.2.1, 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.
+The npm tarball should contain 29 files (version 1.2.2, including `TERMS.md`, `lib/resume.mjs` and `plugin/skills/orbit-resume/`). The plugin ZIP should contain 17 files: the portable `plugin.json`, the three canonical skills, the listing icon and the licence, privacy, security and terms documents. Neither should contain tests, `dist/`, credentials or other build residue.
 
 Confirm all three canonical skills are present:
 
@@ -56,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.2.1.tgz --access public --registry https://registry.npmjs.org/
+npm publish ./orbit-thread-1.2.2.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.
@@ -78,7 +78,7 @@ npx orbit-thread@latest doctor --agent both --scope project
 npx orbit-thread@latest uninstall --agent both --scope project --yes
 ```
 
-Also confirm `npx orbit-thread@latest resume` runs read-only in the disposable repository. Verify `latest` resolves to `1.2.1` 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.2` and package metadata points to `shab1h-gh/orbit-thread`.
 
 ## Existing Orbit Handoff users
 

package/docs/SUBMISSION.md

@@ -1,15 +1,15 @@
 # Directory submission
 
-Updated 12 October 2026.
+Updated 12 October 2026 (v1.2.2 resolves the OpenAI Terms URL and conversation-starter findings).
 
 Provider-directory review is separate from npm, GitHub and standalone installation.
 
 ## OpenAI / ChatGPT Plugins Directory
 
-Orbit Thread v1.2.1 is submitted as:
+Orbit Thread v1.2.2 is submitted as:
 
 ```text
-dist/orbit-thread-plugin-1.2.1.zip
+dist/orbit-thread-plugin-1.2.2.zip
 ```
 
 Build it with:
@@ -18,14 +18,14 @@ Build it with:
 npm run build:plugin
 ```
 
-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.
+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. The manifest declares the public [Terms of Service](../TERMS.md) as `termsOfServiceURL` and provides three conversation starters, each at most 128 characters.
 
 ### Submission flow
 
-1. Complete release validation and build the final v1.2.1 ZIP from the release commit/tag.
+1. Complete release validation and build the final v1.2.2 ZIP from the release commit/tag.
 2. Open the OpenAI Plugins publisher dashboard:
    `https://platform.openai.com/plugins`
-3. Upload `orbit-thread-plugin-1.2.1.zip`.
+3. Upload `orbit-thread-plugin-1.2.2.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.2.1 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.2 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

@@ -249,3 +249,24 @@ Results are recorded in the release PR and final report; the checks run were `np
 ### Compatibility with v1.2.0 installations
 
 A project installed with the published `orbit-thread@1.2.0` is updated in place by the 1.2.1 CLI; installed skills, `.orbit-thread/config.json`, living docs and existing handoffs are preserved.
+
+## Orbit Thread v1.2.2 validation
+
+Documentation and metadata release (`release/v1.2.2`) resolving OpenAI plugin submission findings. The v1.2.1 section above is a historical record and is unchanged.
+
+### Changes under validation
+
+- `TERMS.md` is the public Terms of Service, linked from `README.md` and declared as `termsOfServiceURL` in `plugin/plugin.json`.
+- `defaultPrompt` now holds three conversation starters, each at most 128 characters.
+- The stale `publication.release_notes` text (which described v1.1) now describes v1.2.2.
+- `TERMS.md` is included in the npm tarball (29 files) and the plugin ZIP (17 files).
+- `npm run validate` additionally enforces the Terms URL, the prompt count and the 128-character limit.
+- No change to Setup, Handoff or Resume code, skill files, installer logic or the handoff format. No MCP server is added.
+
+### Verified locally
+
+Results are recorded in the release PR and final report. Checks run: `npm test`, `npm run validate`, `npm run scan:public`, `npm run build:plugin`, `npm pack`, `npm run smoke:pack`, `claude plugin validate ./plugin --strict`, `claude plugin validate . --strict` and `git diff --check`.
+
+### Compatibility
+
+Existing v1.2.x installations keep working; `orbit-thread update` refreshes managed skills to 1.2.2 without touching locally edited files. Authenticated native Codex and Claude sessions were not re-run for this metadata-only release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbit-thread",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Token-efficient project setup, checkpoints and coding-session continuity for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
   "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", "resume", "context-efficiency"],
-  "files": ["bin/", "lib/", "plugin/", "docs/", "README.md", "LICENSE", "SECURITY.md", "PRIVACY.md", "CONTRIBUTING.md", "CHANGELOG.md"],
+  "files": ["bin/", "lib/", "plugin/", "docs/", "README.md", "LICENSE", "SECURITY.md", "PRIVACY.md", "TERMS.md", "CONTRIBUTING.md", "CHANGELOG.md"],
   "scripts": {
     "test": "node --test",
     "validate": "node scripts/validate.mjs",

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

@@ -1,7 +1,7 @@
 {
   "name": "orbit-thread",
   "displayName": "Orbit Thread",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "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",

package/plugin/plugin.json

@@ -1,13 +1,24 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "orbit-thread",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Token-efficient project setup, checkpoints and coding-session continuity.",
-  "author": { "name": "Shabih Anwar", "url": "https://github.com/shab1h-gh" },
+  "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", "resume", "codex", "claude-code", "continuity", "project-setup", "developer-tools"],
+  "keywords": [
+    "handoff",
+    "resume",
+    "codex",
+    "claude-code",
+    "continuity",
+    "project-setup",
+    "developer-tools"
+  ],
   "extensions": {
     "com.openai": {
       "interface": {
@@ -16,18 +27,27 @@
         "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", "Resume coding sessions"],
+        "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, resume a fresh coding session, or save verified current state at a meaningful checkpoint."],
+        "defaultPrompt": [
+          "Set up this coding project for continuity with lightweight docs and agent instructions.",
+          "Save a verified handoff with completed work, risks and the next steps.",
+          "Resume coding from the latest handoff, current Git state and relevant project docs."
+        ],
         "brandColor": "#4338CA",
         "composerIcon": "./assets/icon.png",
-        "logo": "./assets/icon.png"
+        "logo": "./assets/icon.png",
+        "termsOfServiceURL": "https://github.com/shab1h-gh/orbit-thread/blob/main/TERMS.md"
       },
       "onboardingSkill": "./skills/orbit-setup/SKILL.md",
       "publication": {
-        "release_notes": "Orbit Thread v1.1 adds project setup, living docs, configurable subagent preferences, automatic meaningful checkpoints, fresh-context recovery and Orbit Handoff migration support."
+        "release_notes": "Orbit Thread v1.2.2 adds public Terms of Service metadata and shorter conversation starters for directory submission. Setup, Handoff and Resume behaviour is unchanged."
       }
     }
   }