v0.2.1

Paraphe v0.2.1

The release that makes every card explain its situation before it asks — in plain words, with no tracker codes or build jargon as the subject.

What changed

• Context first, in plain words, taught at discovery. The four asking tools (ask_question, request_approval, request_feedback, update_request) and how_to_use now carry the same rule: open with one or two sentences on the situation and why the owner is asked, before the question; keep identifiers in ticket / links.
• copy_notes — the service flags junk copy without ever blocking it. Every create, duplicate and update result names what to fix: a tracker key or a commit hash in the headline, a code in a choice label, a build-jargon token, or an empty context / details. The card is still created and sent as written; the note asks for the fix on the next card.
• The writing standard, in the docs and both skills. docs/tools.md gains rule 4 with a French before/after pair; the repository skill and the owner's personal skill teach the same three techniques (the re-pitch with context first, simplified-technical writing, the product vocabulary); the demo card's question now carries the goal.

Why it matters to you

A card you receive on your phone should read like a situation and a question, not a build report. This release teaches every agent that writes you a card to do that, and hands the sender a small, non-blocking note when the copy still slips.

Quick start

Unchanged: serve the inbox locally (python3 -m paraphe.inbox, PARAPHE_MCP_HOST/PARAPHE_MCP_PORT, store at PARAPHE_STORE_PATH), then call it with the bundled shim:

paraphe-send ask_question '{"question": "...", "choices": ["Approve", "Deny"]}'
paraphe-send list_pending
paraphe-send get_response '{"external_id": "<the id returned at create>"}'

Upgrade: pip install --upgrade paraphe==0.2.1

v0.2.0

Paraphe v0.2.0

The release that makes an owner's answer provable — an agent can match your decision to the exact card it sent, and can never mistake a lost acknowledgement for a missing answer.

What changed

• Stable external identity. Every created request and its response carry an immutable external_id (plus an integer version and the kind), so a reader can look an answer up by identity instead of guessing by timing or text.
• Lost create-acknowledgement recovery by lookup. When the agent never saw the create reply, it recovers the card through the external-ID lookup — it never replays creation. No duplicate card on your phone.
• Default offered choices on the response envelope. A card always carries the choices it offered, so an answer can be validated against exactly what was asked.

Why it matters to you

The auto-lane parks a task when it needs your decision, frees the worker, and resumes it when your answer arrives. That resume is only safe if the answer is bound to the exact card — this release is what makes that binding possible end to end, and what makes a free-text reply correctly not count as authorisation.

Quick start

Serve the inbox locally (python3 -m paraphe.inbox, PARAPHE_MCP_HOST/PARAPHE_MCP_PORT, store at PARAPHE_STORE_PATH), then call it with the bundled shim:

paraphe-send ask_question '{"question": "...", "choices": ["Approve", "Deny"]}'
paraphe-send list_pending
paraphe-send get_response '{"external_id": "<the id returned at create>"}'

Upgrade: pip install --upgrade paraphe==0.2.0

v0.1.3

What changed

• The card composition standard now ships as a repository skill: skills/paraphe-owner-decision-writing/SKILL.md — plain words for the owner, choices as actions with the recommended one first, a plus and a minus per choice, honest risk, the field limits in one table, and a pre-send checklist. The README and docs/tools.md point to it.
• No runtime change: src/, tests and the renderer are untouched.

Install

pip install paraphe

Python 3.11 or newer, and nothing else. In a checkout: python3 -m venv .venv && .venv/bin/pip install ., copy config.example.toml to paraphe.toml, fill in the two values you make up, and run .venv/bin/paraphe --config paraphe.toml — the ready line tells you where to ask. To send decisions to your phone, follow the two Telegram steps in the README.

v0.1.2

What's new in v0.1.2

• Safe legacy store relocation (#16, by @KEYUR141): paraphe store relocate copies the legacy /var/lib/paraphe/inbox.sqlite store into the current per-user location — copy by default, --move to remove the source only after a verified install. It refuses to overwrite a target, verifies the SQLite snapshot before installing it, and keeps the 0600/0700 modes. Closes #3.
• The card writing contract on every shipping surface (#17): a card that reaches the phone carries its origin and its purpose first, with plain tap semantics. The shipped paraphe-return-path skill, the spec, the tools doc, the adapters note and the served how_to_use / asking-tool descriptions now teach it, pinned by a test. Includes the repository wiki refresh.

Quick start

Python 3.11 or newer, and nothing else.

pip install paraphe

In a checkout, the same install inside a virtual environment, with a configuration file to start from:

python3 -m venv .venv
.venv/bin/pip install .
cp config.example.toml paraphe.toml     # then fill in two values you make up
.venv/bin/paraphe --config paraphe.toml

Those two values are yours: mcp_create_bearer (the agent — it creates cards and reads answers) and owner_answer_token (you — it answers them, and it is never given to an agent).

v0.1.1

What changed since v0.1.0

• paraphe --version and python3 -m paraphe --version print the installed
  version, read from the distribution metadata (#1).
• The phone destination ships its owner-side setup path: the README walkthrough
  and paraphe check telegram, which names the bot and verifies delivery to
  the configured owner before a real card is used (#2).
• Docs: the fork contribution procedure, the issue chooser contact links, and
  the ruleset check list.

Install and run

Python 3.11 or newer, and nothing else.

pip install paraphe

In a checkout, the same install inside a virtual environment, with a
configuration file to start from:

python3 -m venv .venv
.venv/bin/pip install .

cp config.example.toml paraphe.toml     # then fill in two values you make up
.venv/bin/paraphe --config paraphe.toml

Those two values are yours:

Value	Who holds it
mcp_create_bearer	the agent. It creates cards and reads answers.
owner_answer_token	you. It answers them, and it is never given to an agent.

With pip install paraphe and no checkout, create paraphe.toml with those
two lines; Paraphe reads it from the directory it runs in.

Paraphe ready: mcp http://127.0.0.1:8787/mcp answer-path on

To send decisions to your phone:

1. Open Telegram's BotFather, run /newbot, and keep the token it gives you
   private.

2. Open the new bot and send it /start. Find your own numeric Telegram user
   id using a user-info bot you trust.

3. Set bot_token and owner_telegram_id in paraphe.toml, then check the
   pair before starting the server:

   .venv/bin/paraphe check telegram
   .venv/bin/paraphe --config paraphe.toml

The check names the bot and sends a plain setup message to your phone. It does
not print the token or create a decision card.

Or run the container, with the data location mounted:

mkdir -p paraphe-data && chmod 0777 paraphe-data
docker build -t paraphe .
docker run --rm -v "$PWD/paraphe-data:/data" \
  -e PARAPHE_MCP_CREATE_BEARER=... -e PARAPHE_OWNER_ANSWER_TOKEN=... paraphe

v0.1.0

Install and run

Python 3.11 or newer, and nothing else.

pip install paraphe

In a checkout, the same install inside a virtual environment, with a
configuration file to start from:

python3 -m venv .venv
.venv/bin/pip install .

cp config.example.toml paraphe.toml     # then fill in two values you make up
.venv/bin/paraphe --config paraphe.toml

Those two values are yours:

Value	Who holds it
mcp_create_bearer	the agent. It creates cards and reads answers.
owner_answer_token	you. It answers them, and it is never given to an agent.

With pip install paraphe and no checkout, create paraphe.toml with those
two lines; Paraphe reads it from the directory it runs in.

Paraphe ready: mcp http://127.0.0.1:8787/mcp answer-path on

Add a Telegram bot token and your Telegram user id to paraphe.toml and
decisions arrive as a message with buttons instead of on the console. Without
them the card is printed where you are looking, which is what the run above
does.

Or run the container, with the data location mounted:

mkdir -p paraphe-data && chmod 0777 paraphe-data
docker build -t paraphe .
docker run --rm -v "$PWD/paraphe-data:/data" \
  -e PARAPHE_MCP_CREATE_BEARER=... -e PARAPHE_OWNER_ANSWER_TOKEN=... paraphe

It binds loopback inside the container, because the answer path refuses a
non-loopback bind. To reach it from outside, configure the phone destination
(a bot token and your Telegram id) and set PARAPHE_MCP_HOST=0.0.0.0; the
answer path is then off, and taps arrive on the phone.