chore: relocate and dedupe specstory transcripts

.clinerules

@@ -0,0 +1,67 @@
+<!-- oboe-mcp:start -->
+<!--
+Copyright (C) 2026 Gregory R. Warnes
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This file is part of Oboe MCP.
+For commercial licensing, contact greg@warnes-innovations.com
+-->
+
+# OBO Session Guidelines
+
+Use the OBO MCP tools for all One-By-One review session work in this repository.
+
+## When To Use OBO
+
+- Use OBO when the user asks to process findings, tasks, or decisions one at a time.
+- Use OBO when multiple review findings need explicit sequential approval instead of a flat summary.
+- Use OBO when the item list should be resumable and persisted outside the current chat transcript.
+- Use OBO when the work may need reordering, blocker tracking, or nested child sessions.
+- Prefer normal chat for small single-step tasks that do not need queue state.
+
+## Required Workflow
+
+- Never directly create, edit, repair, or reorder files in `.github/obo_sessions/`.
+- Use `obo_list_sessions` before starting a new OBO session.
+- If an incomplete session exists, use the agent's structured question UI/tool when available to ask whether to resume, merge, replace, or stop.
+- Use `obo_create` to start a new session. `items` is optional; if items are not yet known, omit them and add them later with `obo_merge_items`.
+- Use `obo_merge_items` to append new findings to an existing session.
+- Start the session with an overview of scope, major dependencies, and proposed order.
+- Use `obo_next` to fetch the next actionable item.
+- Use `obo_mark_in_progress` when beginning work on an item.
+- Use `obo_mark_blocked` when an item cannot proceed and the blocker should be stored.
+- Use `obo_create_child_session` when a nested sub-session is needed.
+- Use `obo_complete_child_session` to finish the child and resume the parent.
+- Use `obo_set_approval` to record approval decisions, timing, and delayed-review transitions.
+- Use `obo_mark_complete` or `obo_mark_skip` to resolve an item.
+- Use `obo_session_status` or `obo_list_items` instead of reading `index.json` directly.
+- Use `obo_complete_session` when all actionable items are resolved.
+- Use the agent's structured question UI/tool for predefined OBO choices such as resume, merge, replace, approval, navigation, stop, restore, and reorder instead of plain-text numbered menus.
+- Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended; state that reason explicitly before falling back.
+
+## Session Conventions
+
+- Session files live in `.github/obo_sessions/`.
+- New session filenames must follow `session_YYYYMMDD_HHMMSS.json`.
+- Item lifecycle states include `pending`, `in_progress`, `deferred`, `blocked`, `completed`, and `skipped`.
+- Item approval states include `unreviewed`, `approved`, and `denied`; approval timing is stored in `approval_mode` as `immediate`, `delayed`, or `null`.
+- Parent sessions may be `paused` while a child session is active.
+- Treat the MCP server as the source of truth for session state.
+
+## Review Behavior
+
+- For multiple findings, keep the OBO session updated after every user-approved action.
+- For a single finding, still use the MCP session flow if the user asks for OBO handling.
+- If a needed operation is not available through the MCP tools, tell the user instead of editing session JSON manually.
+
+## Release Workflow
+
+- Treat testing, tagging, releasing, and publishing as a staged workflow: inspect repo state, run tests, complete release-prep edits, validate packaging, then handle remote release steps.
+- Prefer the verified release test command `.venv/bin/python -m pytest tests/test_session.py tests/test_server.py` unless the user explicitly requests a different scope.
+- Keep release edits minimal and targeted. Do not revert unrelated dirty-worktree files unless the user explicitly asks.
+- Before any irreversible action, pause for confirmation even if the user's initial request already said to publish.
+- The required confirmation boundary includes each of these actions: `git push`, tag creation, GitHub release creation, and PyPI publication.
+- When asking for confirmation, summarize the exact action, the version, and the branch or tag involved.
+- After a live publish, verify the result end to end: release workflow status, PyPI visibility, and at least one package resolution or install check.
+- If clarification, triage, or blocker handling is needed during release work, prefer creating or resuming an OBO session instead of handling it as an unstructured side conversation.
+<!-- oboe-mcp:end -->

.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project.md

@@ -0,0 +1,56 @@
+<!-- Generated by SpecStory, Markdown v2.1.0 -->
+
+# 2026-04-21 13:08:13Z
+
+<!-- copilotide Session e7b88cd6-097d-430f-bb97-7e4bdf9a28ad (2026-04-21 13:08:13Z) -->
+
+_**User (2026-04-21 13:08:13Z)**_
+
+Issues with the install script in `linkedown`:
+```
+(oboe-mcp) ➜  linkedown git:(main) ✗ ./install.sh 
+cp: /Users/warnes/src/linkedown/agent-instructions/copilot-instructions.md: No such file or directory
+(oboe-mcp) ➜  linkedown git:(main) ✗ 
+```
+
+---
+
+_**Agent (copilot/gpt-4.1)**_
+
+MANDATORY PRE-FLIGHT:  
+This task involves troubleshooting a shell install script in the linkedown repo. The following instructions and skills apply:
+
+- From linkedown/AGENTS.md: OBO session guidelines, but not directly relevant to install script fixes.
+- From user memory: Shell patterns (write temp files to project tmp/), but not directly relevant unless script is modified.
+- No direct project-specific install script skill, but general shell scripting and error handling best practices apply.
+
+Relevant skills:
+- code-review (for reviewing/fixing the script)
+- workflow-orchestration (for planning the fix)
+- agent-customization (if the script is meant to copy agent instructions)
+
+First, I will inspect the contents of linkedown/install.sh and the agent-instructions/ directory 
+
+---
+
+_**User (2026-04-21 13:25:50Z)**_
+
+Create agent instructions for the four supported agents following the pattern set in `oboe-mcp/`.
+
+_**User (2026-04-21 13:33:33Z)**_
+
+You misunderstood.  You should create files that provide agent instructions on how to use the linkedown project, not the oboe-mcp project.
+
+_**User (2026-04-21 13:57:57Z)**_
+
+Please evaluate the linkedown agent instructions for clarify and completeness.
+
+_**User (2026-04-21 13:59:54Z)**_
+
+Should we move the `install.sh` file into `agent-instructions` and/or rename it (perhaps `install-agent-instructions.sh` to clarify what it does?
+
+_**User (2026-04-21 14:00:11Z)**_
+
+Yes.
+
+<!-- specstory-relocated: processed=2026-04-21T17:14:20Z source=cv-builder target=linkedown reason="first-path signal (signal2) points to linkedown" -->

.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated2.md

@@ -0,0 +1,56 @@
+<!-- Generated by SpecStory, Markdown v2.1.0 -->
+
+# 2026-04-21 13:08:13Z
+
+<!-- VS Code Copilot IDE Session e7b88cd6-097d-430f-bb97-7e4bdf9a28ad (2026-04-21 13:08:13Z) -->
+
+_**User (2026-04-21 13:08:13Z)**_
+
+Issues with the install script in `linkedown`:
+```
+(oboe-mcp) ➜  linkedown git:(main) ✗ ./install.sh 
+cp: /Users/warnes/src/linkedown/agent-instructions/copilot-instructions.md: No such file or directory
+(oboe-mcp) ➜  linkedown git:(main) ✗ 
+```
+
+---
+
+_**Agent (copilot/gpt-4.1)**_
+
+MANDATORY PRE-FLIGHT:  
+This task involves troubleshooting a shell install script in the linkedown repo. The following instructions and skills apply:
+
+- From linkedown/AGENTS.md: OBO session guidelines, but not directly relevant to install script fixes.
+- From user memory: Shell patterns (write temp files to project tmp/), but not directly relevant unless script is modified.
+- No direct project-specific install script skill, but general shell scripting and error handling best practices apply.
+
+Relevant skills:
+- code-review (for reviewing/fixing the script)
+- workflow-orchestration (for planning the fix)
+- agent-customization (if the script is meant to copy agent instructions)
+
+First, I will inspect the contents of linkedown/install.sh and the agent-instructions/ directory 
+
+---
+
+_**User (2026-04-21 13:25:50Z)**_
+
+Create agent instructions for the four supported agents following the pattern set in `oboe-mcp/`.
+
+_**User (2026-04-21 13:33:33Z)**_
+
+You misunderstood.  You should create files that provide agent instructions on how to use the linkedown project, not the oboe-mcp project.
+
+_**User (2026-04-21 13:57:57Z)**_
+
+Please evaluate the linkedown agent instructions for clarify and completeness.
+
+_**User (2026-04-21 13:59:54Z)**_
+
+Should we move the `install.sh` file into `agent-instructions` and/or rename it (perhaps `install-agent-instructions.sh` to clarify what it does?
+
+_**User (2026-04-21 14:00:11Z)**_
+
+Yes.
+
+<!-- specstory-relocated: processed=2026-05-18T22:21:17Z source=cv-builder target=linkedown reason="first write path /Users/warnes/src/linkedown/agent-instructions/copilot-instructions.md:" -->

AGENTS.md

@@ -0,0 +1,67 @@
+<!-- oboe-mcp:start -->
+<!--
+Copyright (C) 2026 Gregory R. Warnes
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This file is part of Oboe MCP.
+For commercial licensing, contact greg@warnes-innovations.com
+-->
+
+# OBO Session Guidelines
+
+Use the OBO MCP tools for all One-By-One review session work in this repository.
+
+## When To Use OBO
+
+- Use OBO when the user asks to process findings, tasks, or decisions one at a time.
+- Use OBO when multiple review findings need explicit sequential approval instead of a flat summary.
+- Use OBO when the item list should be resumable and persisted outside the current chat transcript.
+- Use OBO when the work may need reordering, blocker tracking, or nested child sessions.
+- Prefer normal chat for small single-step tasks that do not need queue state.
+
+## Required Workflow
+
+- Never directly create, edit, repair, or reorder files in `.github/obo_sessions/`.
+- Use `obo_list_sessions` before starting a new OBO session.
+- If an incomplete session exists, use the agent's structured question UI/tool when available to ask whether to resume, merge, replace, or stop.
+- Use `obo_create` to start a new session. `items` is optional; if items are not yet known, omit them and add them later with `obo_merge_items`.
+- Use `obo_merge_items` to append new findings to an existing session.
+- Start the session with an overview of scope, major dependencies, and proposed order.
+- Use `obo_next` to fetch the next actionable item.
+- Use `obo_mark_in_progress` when beginning work on an item.
+- Use `obo_mark_blocked` when an item cannot proceed and the blocker should be stored.
+- Use `obo_create_child_session` when a nested sub-session is needed.
+- Use `obo_complete_child_session` to finish the child and resume the parent.
+- Use `obo_set_approval` to record approval decisions, timing, and delayed-review transitions.
+- Use `obo_mark_complete` or `obo_mark_skip` to resolve an item.
+- Use `obo_session_status` or `obo_list_items` instead of reading `index.json` directly.
+- Use `obo_complete_session` when all actionable items are resolved.
+- Use the agent's structured question UI/tool for predefined OBO choices such as resume, merge, replace, approval, navigation, stop, restore, and reorder instead of plain-text numbered menus.
+- Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended; state that reason explicitly before falling back.
+
+## Session Conventions
+
+- Session files live in `.github/obo_sessions/`.
+- New session filenames must follow `session_YYYYMMDD_HHMMSS.json`.
+- Item lifecycle states include `pending`, `in_progress`, `deferred`, `blocked`, `completed`, and `skipped`.
+- Item approval states include `unreviewed`, `approved`, and `denied`; approval timing is stored in `approval_mode` as `immediate`, `delayed`, or `null`.
+- Parent sessions may be `paused` while a child session is active.
+- Treat the MCP server as the source of truth for session state.
+
+## Review Behavior
+
+- For multiple findings, keep the OBO session updated after every user-approved action.
+- For a single finding, still use the MCP session flow if the user asks for OBO handling.
+- If a needed operation is not available through the MCP tools, tell the user instead of editing session JSON manually.
+
+## Release Workflow
+
+- Treat testing, tagging, releasing, and publishing as a staged workflow: inspect repo state, run tests, complete release-prep edits, validate packaging, then handle remote release steps.
+- Prefer the verified release test command `.venv/bin/python -m pytest tests/test_session.py tests/test_server.py` unless the user explicitly requests a different scope.
+- Keep release edits minimal and targeted. Do not revert unrelated dirty-worktree files unless the user explicitly asks.
+- Before any irreversible action, pause for confirmation even if the user's initial request already said to publish.
+- The required confirmation boundary includes each of these actions: `git push`, tag creation, GitHub release creation, and PyPI publication.
+- When asking for confirmation, summarize the exact action, the version, and the branch or tag involved.
+- After a live publish, verify the result end to end: release workflow status, PyPI visibility, and at least one package resolution or install check.
+- If clarification, triage, or blocker handling is needed during release work, prefer creating or resuming an OBO session instead of handling it as an unstructured side conversation.
+<!-- oboe-mcp:end -->

CLAUDE.md

@@ -0,0 +1,67 @@
+<!-- oboe-mcp:start -->
+<!--
+Copyright (C) 2026 Gregory R. Warnes
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This file is part of Oboe MCP.
+For commercial licensing, contact greg@warnes-innovations.com
+-->
+
+# OBO Session Guidelines
+
+Use the OBO MCP tools for all One-By-One review session work in this repository.
+
+## When To Use OBO
+
+- Use OBO when the user asks to process findings, tasks, or decisions one at a time.
+- Use OBO when multiple review findings need explicit sequential approval instead of a flat summary.
+- Use OBO when the item list should be resumable and persisted outside the current chat transcript.
+- Use OBO when the work may need reordering, blocker tracking, or nested child sessions.
+- Prefer normal chat for small single-step tasks that do not need queue state.
+
+## Required Workflow
+
+- Never directly create, edit, repair, or reorder files in `.github/obo_sessions/`.
+- Use `obo_list_sessions` before starting a new OBO session.
+- If an incomplete session exists, use the agent's structured question UI/tool when available to ask whether to resume, merge, replace, or stop.
+- Use `obo_create` to start a new session. `items` is optional; if items are not yet known, omit them and add them later with `obo_merge_items`.
+- Use `obo_merge_items` to append new findings to an existing session.
+- Start the session with an overview of scope, major dependencies, and proposed order.
+- Use `obo_next` to fetch the next actionable item.
+- Use `obo_mark_in_progress` when beginning work on an item.
+- Use `obo_mark_blocked` when an item cannot proceed and the blocker should be stored.
+- Use `obo_create_child_session` when a nested sub-session is needed.
+- Use `obo_complete_child_session` to finish the child and resume the parent.
+- Use `obo_set_approval` to record approval decisions, timing, and delayed-review transitions.
+- Use `obo_mark_complete` or `obo_mark_skip` to resolve an item.
+- Use `obo_session_status` or `obo_list_items` instead of reading `index.json` directly.
+- Use `obo_complete_session` when all actionable items are resolved.
+- Use the agent's structured question UI/tool for predefined OBO choices such as resume, merge, replace, approval, navigation, stop, restore, and reorder instead of plain-text numbered menus.
+- Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended; state that reason explicitly before falling back.
+
+## Session Conventions
+
+- Session files live in `.github/obo_sessions/`.
+- New session filenames must follow `session_YYYYMMDD_HHMMSS.json`.
+- Item lifecycle states include `pending`, `in_progress`, `deferred`, `blocked`, `completed`, and `skipped`.
+- Item approval states include `unreviewed`, `approved`, and `denied`; approval timing is stored in `approval_mode` as `immediate`, `delayed`, or `null`.
+- Parent sessions may be `paused` while a child session is active.
+- Treat the MCP server as the source of truth for session state.
+
+## Review Behavior
+
+- For multiple findings, keep the OBO session updated after every user-approved action.
+- For a single finding, still use the MCP session flow if the user asks for OBO handling.
+- If a needed operation is not available through the MCP tools, tell the user instead of editing session JSON manually.
+
+## Release Workflow
+
+- Treat testing, tagging, releasing, and publishing as a staged workflow: inspect repo state, run tests, complete release-prep edits, validate packaging, then handle remote release steps.
+- Prefer the verified release test command `.venv/bin/python -m pytest tests/test_session.py tests/test_server.py` unless the user explicitly requests a different scope.
+- Keep release edits minimal and targeted. Do not revert unrelated dirty-worktree files unless the user explicitly asks.
+- Before any irreversible action, pause for confirmation even if the user's initial request already said to publish.
+- The required confirmation boundary includes each of these actions: `git push`, tag creation, GitHub release creation, and PyPI publication.
+- When asking for confirmation, summarize the exact action, the version, and the branch or tag involved.
+- After a live publish, verify the result end to end: release workflow status, PyPI visibility, and at least one package resolution or install check.
+- If clarification, triage, or blocker handling is needed during release work, prefer creating or resuming an OBO session instead of handling it as an unstructured side conversation.
+<!-- oboe-mcp:end -->

README.md

@@ -6,13 +6,35 @@ LinkedIn does not render Markdown, but does display Unicode styled characters co
 `linkedown` converts between the two formats — both as a CLI tool and as an MCP server
 for use by coding agents.
 
+
 The Markdown → LinkedIn conversion logic is derived from
 [md-to-linkedin](https://github.com/shenning00/md-to-linkedin) by Scott Henning (MIT).
 
+## Agent instructions for Copilot, Claude, Codex, and Cline
+
+To enable agent-aware workflows, `linkedown` provides example agent instruction files for Copilot, Claude, Codex, and Cline in the `agent-instructions/` directory.
+
+To install these instructions for your VS Code agents, run:
+
+```sh
+cd agent-instructions
+./install-agent-instructions.sh
+```
+
+This will copy the following files to your VS Code user data directory:
+- `copilot-instructions.md`
+- `CLAUDE.md`
+- `codex-instructions.md`
+- `cline-instructions.md`
+
+You can customize these files as needed for your workflow. See `agent-instructions/README.md` for details.
+
 ## Installation
 
 ```sh
 pip install linkedown
+# or 
+pipx install linkedown
 ```
 
 ## CLI usage

agent-instructions/CLAUDE.md

@@ -0,0 +1,20 @@
+# Claude Agent Instructions for linkedown
+
+## Overview
+linkedown provides Markdown ↔ LinkedIn Unicode conversion as both a CLI and an MCP server.
+
+### CLI Usage
+- Convert Markdown to LinkedIn Unicode: `md2li input.md [-o output.txt] [--copy]`
+- Convert LinkedIn Unicode to Markdown: `li2md input.txt [-o output.md]`
+
+### MCP Server
+- Start with: `linkedown-mcp`
+- Exposes tools: `md_to_linkedin_tool`, `linkedin_to_md_tool`
+
+### Agent Guidance
+- Use CLI for file/clipboard conversion.
+- Use MCP server for agent-driven conversion tasks.
+- Refer to the README for formatting details and examples.
+
+---
+For installation, see agent-instructions/README.md.

agent-instructions/README.md

@@ -0,0 +1,15 @@
+# Agent Instructions for linkedown
+
+This directory contains example agent instruction files for Copilot, Claude, Codex, and Cline. To install them for your VS Code agents, run:
+
+```sh
+./install-agent-instructions.sh
+```
+
+This will copy the following files to your VS Code user data directory:
+- `copilot-instructions.md`
+- `CLAUDE.md`
+- `codex-instructions.md`
+- `cline-instructions.md`
+
+You can customize these files as needed for your workflow.