open-research-protocol 0.4.13 → 0.4.15

package/docs/AGENT_LOOP.md

@@ -6,6 +6,10 @@ Use this loop when an AI agent is the primary operator of an ORP-enabled repo.
 
 - Read `llms.txt`.
 - Run `orp about --json`.
+- If the task benefits from fresh concepting, tasteful interface work, or
+  exploratory reframing, run:
+  - `orp mode nudge sleek-minimal-progressive --json`
+  - Treat it as an optional lens for deeper, wider, top-down, or rotated perspective shifts.
 - If packs matter, run `orp pack list --json`.
 - Read `PROTOCOL.md` before making claims.
 - If the task is external OSS contribution workflow or PR governance, read
@@ -16,6 +20,13 @@ Use this loop when an AI agent is the primary operator of an ORP-enabled repo.
 ## 2. Select Work
 
 - Identify the target profile and canonical artifact paths.
+- If the task needs an API key or token that is not already available, save it first:
+  - human interactive path:
+    - `orp secrets add --alias <alias> --label "<label>" --provider <provider>`
+  - agent/script path:
+    - `printf '%s' '<secret>' | orp secrets add --alias <alias> --label "<label>" --provider <provider> --value-stdin`
+  - convenience path:
+    - `orp secrets ensure --alias <alias> --provider <provider> --current-project --json`
 - If a pack-backed workflow needs setup, run:
   - `orp pack install --pack-id <pack-id> --json`
   - or `orp pack fetch --source <git-url> --pack-id <pack-id> --install-target . --json`
@@ -24,6 +35,8 @@ Use this loop when an AI agent is the primary operator of an ORP-enabled repo.
 - If the task begins from a public YouTube link, normalize it first:
   - `orp youtube inspect <youtube-url> --json`
   - or `orp youtube inspect <youtube-url> --save --json` when the source artifact should stay with the repo
+- If the task depends on understanding another local repo or project directory deeply, synthesize it first:
+  - `orp exchange repo synthesize /path/to/source --json`
 
 ## 3. Run
 

package/docs/AGENT_MODES.md

@@ -0,0 +1,79 @@
+# ORP Agent Modes
+
+ORP agent modes are lightweight cognitive overlays.
+
+They do not change ORP's evidence boundary, artifact model, or canonical
+workflow surfaces. They exist to help an agent adjust taste and exploratory
+behavior intentionally.
+
+They are optional.
+
+Think of them as paint colors or lenses an agent or user can pick up when the
+work needs a different feel or perspective. They should not feel forced,
+contrived, or permanently switched on.
+
+## Built-In Modes
+
+### `sleek-minimal-progressive`
+
+Purpose:
+
+- keep outputs clean without becoming generic
+- create fresh movement when a project feels flat or trapped
+- help the operator dive deeper, step back top-down, zoom wider, or rotate the angle
+- preserve one surprising move long enough to evaluate it
+- bias toward momentum and graceful next steps
+
+Recommended commands:
+
+```bash
+orp mode list --json
+orp mode show sleek-minimal-progressive --json
+orp mode nudge sleek-minimal-progressive --json
+```
+
+Operational idea:
+
+- `list` tells the agent what modes exist
+- `show` returns the full reminder, ritual, questions, and anti-patterns
+- `nudge` returns one deterministic creativity card that can be used as a
+  short-lived prompt overlay for the next drafting or design pass
+
+The `nudge` surface is intentionally small. It should create motion and taste,
+not replace the main task or force novelty for its own sake.
+
+Use this mode when:
+
+- the work feels stuck in one framing
+- a solution is serviceable but not alive
+- you need a deliberate perspective shift
+- you want to invite a bit more play without losing structure
+
+### `ruthless-simplification`
+
+Use this when the work is swollen, muddy, or overloaded. It is the "cut to the
+live core" mode.
+
+- collapse branches
+- remove ornamental complexity
+- find the shortest honest shape
+- recover momentum through clarity
+
+### `systems-constellation`
+
+Use this when the local move is probably part of a larger field of constraints,
+dependencies, and downstream effects.
+
+- step back top-down
+- inspect upstream and downstream impacts
+- think in loops and time horizons
+- choose the system move, not just the local patch
+
+### `bold-concept-generation`
+
+Use this when the work needs bigger options before it needs tighter polish.
+
+- generate stronger conceptual directions
+- import principles from other domains
+- keep one unreasonable idea alive long enough to inspect it
+- prune only after a genuinely bold pass exists

package/docs/CANONICAL_CLI_BOUNDARY.md

@@ -136,6 +136,7 @@ Commands:
 
 - `orp auth ...`
 - `orp ideas ...`
+- `orp workspaces ...` (first-class hosted workspace records)
 - `orp feature ...`
 - `orp world ...`
 - `orp checkpoint ...`
@@ -146,10 +147,24 @@ This is the canonical client for:
 
 - hosted auth/session state
 - idea and world binding
+- hosted workspace list/detail/timeline/state update semantics
 - checkpoint queueing
 - runner polling/SSE wake-up
 - lease/claim/start/complete/cancel/retry behavior
 
+Current bridge:
+
+- `orp workspace sync ...` may still mirror local workspace state into linked
+  idea notes for compatibility.
+
+Canonical target:
+
+- hosted workspace records are first-class and are not defined by idea notes
+- the exact contract lives in:
+  - `spec/v1/hosted-workspace.schema.json`
+  - `spec/v1/hosted-workspace-event.schema.json`
+  - `docs/ORP_HOSTED_WORKSPACE_CONTRACT.md`
+
 ### 5. Reasoning Kernel
 
 Commands:

package/docs/EXCHANGE.md

@@ -0,0 +1,94 @@
+# ORP Knowledge Exchange
+
+`orp exchange repo synthesize` is ORP's deeper repository-synthesis surface.
+
+It is different from `orp discover`:
+
+- `discover` is breadth-first scanning and ranking
+- `exchange` is depth-first synthesis and transfer mapping
+
+The goal is to turn another codebase or project directory into structured
+knowledge you can reuse inside the current repo.
+
+## Why this exists
+
+Agents and humans often do not just need to *find* promising repositories.
+They need to understand:
+
+- what a source repo is really doing
+- how it is organized
+- what patterns are reusable
+- what its workflows imply
+- and how it can help the current project
+
+That calls for a more harnessed, repo-native artifact flow than a default scan.
+
+## Command
+
+```bash
+orp exchange repo synthesize /path/to/source --json
+```
+
+If the source is a plain local directory and you want ORP to bootstrap git
+tracking there first:
+
+```bash
+orp exchange repo synthesize /path/to/source --allow-git-init --json
+```
+
+Remote git references are also accepted:
+
+```bash
+orp exchange repo synthesize owner/repo --json
+orp exchange repo synthesize https://github.com/owner/repo.git --json
+```
+
+## Source modes
+
+ORP currently supports:
+
+- `local_git`
+- `local_directory`
+- `remote_git`
+
+For local non-git directories, ORP will only mutate the source when
+`--allow-git-init` is explicitly provided.
+
+## Artifacts
+
+Each exchange run writes:
+
+- `orp/exchange/<exchange_id>/EXCHANGE.json`
+- `orp/exchange/<exchange_id>/EXCHANGE_SUMMARY.md`
+- `orp/exchange/<exchange_id>/TRANSFER_MAP.md`
+
+These artifacts are synthesis aids, not evidence by themselves.
+
+## What the exchange focuses on
+
+The first slice is intentionally structured around:
+
+- source identity and mode
+- inventory of docs, tests, manifests, and languages
+- relationship to the current project
+- shared languages / manifests / top-level structure
+- suggested focus areas for deeper human or agent analysis
+- transfer mapping and project momentum
+
+The aim is to answer:
+
+- what does this repo know?
+- how is it organized?
+- what can transfer?
+- how does it help us right now?
+
+not just:
+
+- what tasks should we do next?
+
+## Important boundary
+
+Knowledge exchange artifacts are process artifacts.
+
+They help ORP structure understanding and transfer, but they do not replace
+canonical evidence in the source or host repository.

package/docs/LAUNCH_KIT.md

@@ -0,0 +1,107 @@
+# Launch Kit
+
+## Positioning
+
+Short version:
+- ORP is an agent-first CLI for research workflows, workspace ledgers, secrets, scheduling, and governed execution.
+
+Medium version:
+- ORP is a unified CLI surface for turning a project directory into a reusable agent-friendly operating environment: hosted auth, local governance, saved workspaces, scheduled Codex jobs, secrets, packets, reports, and more.
+
+Long version:
+- ORP is meant to feel like one tool that helps operators and agents move from "what am I working on?" to "recover the workspace ledger, resolve the right key, run the next loop, checkpoint the state, and keep the workflow honest." It supports both hosted control-plane flows and local-first repo governance without forcing the user to stitch together a pile of unrelated scripts.
+
+Demo/marketing rule:
+- Public demos and launch materials should use the same human-facing command output ORP actually prints. Do not paraphrase command results into friendlier invented summaries.
+
+## Launch Copy
+
+### One-liner
+- Agent-first CLI for research workflows, saved workspaces, secrets, and governed execution.
+
+### Short post
+- I just shipped `open-research-protocol`, an agent-first CLI for research workflows, saved workspaces, secrets, scheduled Codex jobs, and governed project execution. It is designed to make the local desk and the hosted control plane feel like one surface. Install with `npm install -g open-research-protocol`. GitHub: https://github.com/SproutSeeds/orp
+
+### Longer post
+- I just shipped `open-research-protocol`, a unified CLI for agent-first research and research-like engineering. ORP can keep a hosted workspace ledger synced, manage a hosted secret inventory with optional local Keychain sync, schedule recurring Codex jobs, and still expose the local governance loop for checkpoints, packets, reports, and readiness. The goal is not just "more commands"; it is one coherent operator surface that agents can discover and use without losing track of boundaries.
+
+## Demo Flow
+
+Primary demo flow:
+
+```bash
+npm install -g open-research-protocol
+orp home
+orp workspaces list
+orp auth login
+orp secrets add --alias openai-primary --label "OpenAI Primary" --provider openai
+orp workspace tabs main
+orp schedule add codex --name morning-summary --prompt "Summarize this repo"
+orp checkpoint create -m "capture loop state"
+orp frontier state
+orp exchange repo synthesize /path/to/source
+orp mode nudge sleek-minimal-progressive
+```
+
+Focused workspace demo:
+
+```bash
+orp workspace list
+orp workspace tabs main
+orp workspace tabs main
+orp workspace add-tab main --path /absolute/path/to/project --resume-command "codex resume <id>"
+orp workspace sync main
+```
+
+Focused secrets demo:
+
+```bash
+orp auth login
+orp secrets add --alias openai-primary --label "OpenAI Primary" --provider openai
+orp secrets list --json
+orp secrets sync-keychain openai-primary --json
+orp secrets resolve openai-primary --reveal --local-first --json
+```
+
+## What To Emphasize
+
+- One CLI surface instead of a scattered bag of scripts.
+- Strong workspace recovery with `workspace tabs main`.
+- Interactive secret save for humans, stdin-based save for agents, plus optional local Keychain sync.
+- Scheduled Codex work without making the operator wire raw cron jobs.
+- Agent-readable discovery surfaces like `orp home --json` and `orp about --json`.
+
+## GitHub Presentation Notes
+
+Recommended repo tagline:
+- Agent-first CLI for research workflows, saved workspaces, secrets, and governed execution.
+
+Recommended demo assets:
+- animated terminal demo: `assets/terminal-demo.gif`
+- poster frame: `assets/terminal-demo-poster.png`
+- storyboard grid: `assets/terminal-demo-storyboard.png`
+- per-scene posters:
+  - `assets/terminal-scene-01-home.png`
+  - `assets/terminal-scene-02-hosted.png`
+  - `assets/terminal-scene-03-secrets.png`
+  - `assets/terminal-scene-04-workspace.png`
+  - `assets/terminal-scene-05-schedule.png`
+  - `assets/terminal-scene-06-governance.png`
+  - `assets/terminal-scene-07-planning.png`
+  - `assets/terminal-scene-08-synthesis.png`
+  - `assets/terminal-scene-09-mode.png`
+
+## npm Presentation Notes
+
+- Keep the README lead readable.
+- Show the terminal demo GIF near the top.
+- Use the demo flow to make the command families concrete quickly.
+- Prefer the workspace + secrets story over listing every possible ORP surface at once.
+
+## Maintainer Notes
+
+Regenerate the terminal demo assets with:
+
+```bash
+npm run render:terminal-demo
+```

package/docs/ORP_HOSTED_WORKSPACE_CONTRACT.md

@@ -0,0 +1,295 @@
+# ORP Hosted Workspace Contract
+
+This document defines the first-class hosted workspace model that should
+replace the current "workspace JSON embedded inside idea notes" bridge.
+
+## Status
+
+The current implementation in this repo is still bridge-first:
+
+- local workspace state can live in a local workspace manifest JSON file
+- hosted workspace state is mirrored into an idea's `notes` field via
+  the fenced ` ```orp-workspace ` block
+- `orp workspace tabs/add-tab/remove-tab/sync` currently read or update that bridge
+
+This document and the accompanying schemas define the next exact contract so
+the web app, hosted backend, and CLI can converge on one durable source of
+truth.
+
+## Canonical Source Of Truth
+
+The canonical hosted source of truth should be one hosted workspace record:
+
+- schema: `spec/v1/hosted-workspace.schema.json`
+- stable id: `workspace_id`
+- one current state object
+- one activity timeline made of workspace events
+
+Idea notes are a compatibility bridge only after this contract lands.
+
+## Resource Model
+
+### Hosted Workspace
+
+One hosted workspace record owns:
+
+- `workspace_id`
+- `title`
+- `description`
+- `visibility`
+- `linked_idea`
+- `state`
+- `latest_event`
+- `metrics`
+
+The important invariant is:
+
+- `state` is the thing ORP opens locally
+- the timeline explains how that state changed over time
+
+### Current State
+
+`state` is the exact recoverable workspace ledger shape:
+
+- current tab order
+- repo/project roots
+- saved `codex resume ...` or `claude --resume ...` commands
+- current focus
+- current trajectory
+- ledger metadata such as host, notes bridge status, and last sync origin
+
+### Timeline Events
+
+Events are append-only and explain why the current state changed:
+
+- workspace created
+- ledger viewed
+- tab added/removed/updated
+- focus summary updated
+- trajectory summary updated
+- bridge synced back to an idea
+
+Schema:
+
+- `spec/v1/hosted-workspace-event.schema.json`
+
+## CLI Contract
+
+To avoid colliding with the existing local launcher surface under
+`orp workspace ...`, the hosted first-class resource should live under:
+
+```bash
+orp workspaces ...
+```
+
+### Hosted Workspace Commands
+
+List hosted workspaces:
+
+```bash
+orp workspaces list [--json]
+```
+
+Show one hosted workspace:
+
+```bash
+orp workspaces show <workspace-id> [--json]
+```
+
+Create one hosted workspace:
+
+```bash
+orp workspaces add --title "ORP Main" [--idea-id <idea-id>] [--json]
+```
+
+Update one hosted workspace:
+
+```bash
+orp workspaces update <workspace-id> [--title <title>] [--description <text>] [--visibility <visibility>] [--json]
+```
+
+Show just the current tabs for one hosted workspace:
+
+```bash
+orp workspaces tabs <workspace-id> [--json]
+```
+
+Show the hosted timeline:
+
+```bash
+orp workspaces timeline <workspace-id> [--limit <n>] [--json]
+```
+
+Append a new hosted snapshot/state push:
+
+```bash
+orp workspaces push-state <workspace-id> --state-file <path> [--json]
+```
+
+Append an agent/user event:
+
+```bash
+orp workspaces add-event <workspace-id> --event-file <path> [--json]
+```
+
+## Local Ledger Bridge Contract
+
+The existing local workspace surface should evolve like this:
+
+Inspect the hosted workspace ledger through the local operator surface:
+
+```bash
+orp workspace tabs --hosted-workspace-id <workspace-id>
+```
+
+Append or remove ledger entries directly:
+
+```bash
+orp workspace add-tab --hosted-workspace-id <workspace-id> --path /absolute/path/to/project --resume-command "codex resume <id>"
+orp workspace remove-tab --hosted-workspace-id <workspace-id> --path /absolute/path/to/project
+```
+
+Compatibility bridge back to the linked idea when needed:
+
+```bash
+orp workspace sync <idea-id> --workspace-file ./workspace.json
+```
+
+The long-term rule is:
+
+- `orp workspace ...` remains the local operator surface for editing and inspecting the workspace ledger
+- `orp workspaces ...` becomes the hosted source-of-truth surface
+
+## Hosted API Contract
+
+The hosted backend should expose these CLI-facing routes:
+
+```text
+GET    /api/cli/workspaces
+POST   /api/cli/workspaces
+GET    /api/cli/workspaces/:workspaceId
+PATCH  /api/cli/workspaces/:workspaceId
+GET    /api/cli/workspaces/:workspaceId/tabs
+GET    /api/cli/workspaces/:workspaceId/timeline
+POST   /api/cli/workspaces/:workspaceId/state
+POST   /api/cli/workspaces/:workspaceId/events
+```
+
+### GET /api/cli/workspaces
+
+Returns a list view for the web app dropdown and agent discovery:
+
+- `workspace_id`
+- `title`
+- `linked_idea`
+- `metrics`
+- `updated_at_utc`
+- `latest_event`
+
+### GET /api/cli/workspaces/:workspaceId
+
+Returns the full hosted workspace record conforming to:
+
+- `spec/v1/hosted-workspace.schema.json`
+
+### GET /api/cli/workspaces/:workspaceId/tabs
+
+Returns a thin projection of the current state for lightweight inspection:
+
+- current ordered tabs
+- path/project root
+- saved resume command or structured resume metadata
+- focus/trajectory excerpts
+
+### GET /api/cli/workspaces/:workspaceId/timeline
+
+Returns newest-first hosted workspace events conforming to:
+
+- `spec/v1/hosted-workspace-event.schema.json`
+
+### POST /api/cli/workspaces/:workspaceId/state
+
+Accepts a new current-state payload and:
+
+- validates the incoming state
+- increments `state.state_version`
+- updates `updated_at_utc`
+- appends a `snapshot.created` event
+
+### POST /api/cli/workspaces/:workspaceId/events
+
+Accepts one explicit event payload and appends it to the timeline.
+
+## Web App Contract
+
+The web app should surface hosted workspaces as a first-class screen.
+
+### Workspace List Screen
+
+The list screen should show:
+
+- workspace title
+- linked idea title
+- tab count
+- project count
+- current focus
+- last updated timestamp
+- latest event summary
+
+This is the dropdown/picker surface the user asked for.
+
+### Workspace Detail Screen
+
+The detail page should show:
+
+- workspace header and linked idea
+- current summary / focus / trajectory
+- ordered tabs with repo roots and session ids
+- per-tab focus summary
+- per-tab trajectory summary
+- current task per tab/project
+- timeline of state changes over time
+
+### Timeline
+
+The timeline should make it easy to answer:
+
+- what changed
+- when it changed
+- whether a tab was added or removed
+- what the agent says is being worked on now
+- where the work appears to be heading
+
+## Agent Write Contract
+
+Agents should be allowed to update structured workspace state rather than only
+free-form notes.
+
+The minimum agent-owned fields are:
+
+- workspace-level `state.summary`
+- workspace-level `state.current_focus`
+- workspace-level `state.trajectory`
+- per-tab `current_task`
+- per-tab `focus_summary`
+- per-tab `trajectory_summary`
+
+Agents should also append explicit timeline events when they make meaningful
+updates so the hosted detail page remains explainable instead of silently
+mutating.
+
+## Migration Rule
+
+Migration should happen in this order:
+
+1. create hosted workspace records linked to existing ideas
+2. copy the current ` ```orp-workspace ` block into `state`
+3. keep mirroring back into idea notes temporarily
+4. update the local launcher to prefer `--hosted-workspace-id`
+5. make idea-note mirroring optional and eventually secondary
+
+## Non-Negotiable Rule
+
+After the hosted workspace model lands, the web app should never invent a
+different workspace state shape from the CLI contract. The CLI contract and
+these schemas remain authoritative.

package/docs/ORP_PUBLIC_LAUNCH_CHECKLIST.md

@@ -16,6 +16,7 @@ Use this checklist when releasing ORP as the unified public CLI and product surf
   - `bash scripts/orp-release-smoke.sh --hosted --codex-session-id <session-id>`
   - `npm i -g open-research-protocol`
   - `orp -h`
+  - `orp workspace -h`
   - `orp init`
   - `orp status --json`
   - `orp branch start work/bootstrap --allow-dirty --json`
@@ -28,6 +29,7 @@ Use this checklist when releasing ORP as the unified public CLI and product surf
   - `orp auth login`
   - `orp whoami --json`
   - `orp ideas list --json`
+  - `orp workspace tabs main`
 
 ## 2. Hosted workspace readiness
 
@@ -53,6 +55,8 @@ Use this checklist when releasing ORP as the unified public CLI and product surf
 
 ## 4. Package release
 
+- Refresh launch assets:
+  - `npm run render:terminal-demo`
 - Bump `package.json` version.
 - Commit and push `main`.
 - Expect `npm publish` to fail if the worktree is dirty or the release commit is not already on GitHub.
@@ -75,6 +79,7 @@ Use this checklist when releasing ORP as the unified public CLI and product surf
 - `npm view open-research-protocol version`
 - `npm i -g open-research-protocol`
 - `orp -h`
+- confirm README renders the terminal demo GIF on GitHub and npm
 - `orp init`
 - `orp status --json`
 - `orp about --json`