Rename starter placeholder to Piper

[lchoquel]

Summary

• rename the template placeholder project, package, and CLI from my-project/my_project to piper
• rework bootstrap replacement logic for the single-token placeholder and keep the renamed CLI/package forms correct
• overhaul the README quick start, expected outputs, demo docs, and Mermaid diagrams
• update Unreleased changelog notes for the rename and docs changes

Verification

• make agent-check
• make agent-test
• make v
• make tb
• uv run piper extract-entities "Lina from Datum Labs met Omar on July 7, 2026."

Release cut is left for a later batch.

[greptile-apps]

Greptile Summary

This PR renames the starter placeholder to piper and updates the demo experience. The main changes are:

• Renamed the project metadata, package, CLI command, imports, tests, and lock metadata to piper.
• Reworked the bootstrap script for the single-token piper / Piper placeholder.
• Expanded the README with quick start output, demo commands, and execution-mode diagrams.
• Added PDF summarization and image-generation demo paths with matching examples, method bundles, and tests.

Confidence Score: 5/5

Safe to merge with minimal risk.

The changes are a coordinated rename plus demo and documentation updates. Bootstrap tests cover the prior survivor-check issue and the renamed CLI paths are covered by unit tests.

No files require special attention.

T-Rex Logs

What T-Rex did

• I reviewed the real Piper extract-entities CLI transcript and noted an API credential blocker (401 Unauthorized) that blocked access, as shown in the verified log.
• Targeted Piper extract-entities CLI tests were executed and all targeted tests passed (17 passed, 2 deselected).
• The extract-entities lint checks (.mthds) passed, confirming static checks are green.
• An agent-test run was attempted but failed due to a missing bootstrap script, blocking progress on agent validation.
• The make v validation completed successfully, confirming the validation step passes.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
.claude/skills/bootstrap/scripts/bootstrap.py	Reworks placeholder replacement around piper / Piper, targeted pyproject.toml edits, package directory rename, and a neutral survivor check.
README.md	Overhauls quick start and demo documentation around the piper CLI, file-input PDF summary, image generation, and execution-mode diagrams.
piper/cli.py	Renames CLI imports and messages to piper and wires the extract, summarize-PDF, generate-image, and run-inspection commands.
piper/runner.py	Renames durable and blocking execution guidance and resume hints to the piper CLI.
piper/file_input.py	Adds document file input encoding to build a base64 data: URL Document envelope for the API.
piper/examples/summarize_pdf.py	Adds the PDF summarization example with typed DocumentSummary output parsing.
piper/examples/generate_image.py	Adds the image generation example with typed parsing for built-in Image output.
piper/methods/summarize-pdf/main.mthds	Adds the PDF summarization method bundle with Document input and structured summary output.
pyproject.toml	Renames project metadata, console script, package discovery, type-checker targets, and lock metadata to piper.
tests/unit/test_bootstrap_script.py	Adds tests for survivor-check handling of requested names containing piper and unhandled placeholder tokens.
tests/unit/test_cli.py	Updates CLI tests for piper commands and adds coverage for PDF document inputs and image prompts.
uv.lock	Regenerates lock metadata for the renamed piper project package.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant User as User / CLI
participant Piper as piper Typer app
participant Runner as piper.runner
participant API as Hosted Pipelex API
participant Parser as piper.examples parser

User->>Piper: "uv run piper <demo> inputs"
Piper->>Piper: read .mthds bundle and build inputs
alt blocking mode
    Piper->>Runner: run_blocking(pipe_code, bundle, inputs)
    Runner->>API: execute(mthds_contents, inputs)
    API-->>Runner: resolved main_stuff
else durable attended/default
    Piper->>Runner: run_durable_attended(pipe_code, bundle, inputs)
    Runner->>API: start(mthds_contents, inputs)
    API-->>Runner: run id
    Runner->>API: wait_for_result(run id)
    API-->>Runner: resolved main_stuff
else durable detached
    Piper->>Runner: start_detached(pipe_code, bundle, inputs)
    Runner->>API: start(mthds_contents, inputs)
    API-->>Runner: run id
    Runner-->>User: print run id for later piper runs wait
end
Runner-->>Piper: RunResults
Piper->>Parser: parse(results.main_stuff)
Parser-->>User: JSON output

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant User as User / CLI
participant Piper as piper Typer app
participant Runner as piper.runner
participant API as Hosted Pipelex API
participant Parser as piper.examples parser

User->>Piper: "uv run piper <demo> inputs"
Piper->>Piper: read .mthds bundle and build inputs
alt blocking mode
    Piper->>Runner: run_blocking(pipe_code, bundle, inputs)
    Runner->>API: execute(mthds_contents, inputs)
    API-->>Runner: resolved main_stuff
else durable attended/default
    Piper->>Runner: run_durable_attended(pipe_code, bundle, inputs)
    Runner->>API: start(mthds_contents, inputs)
    API-->>Runner: run id
    Runner->>API: wait_for_result(run id)
    API-->>Runner: resolved main_stuff
else durable detached
    Piper->>Runner: start_detached(pipe_code, bundle, inputs)
    Runner->>API: start(mthds_contents, inputs)
    API-->>Runner: run id
    Runner-->>User: print run id for later piper runs wait
end
Runner-->>Piper: RunResults
Piper->>Parser: parse(results.main_stuff)
Parser-->>User: JSON output

Loading

_{Reviews (3): Last reviewed commit: "Refactor placeholder survivor check with..." | Re-trigger Greptile}