Add quickstart file-write flow for faster local onboarding

[bmdhodl]

Draft PR

Title

Add quickstart file-write flow for faster local onboarding

Summary

• add agentguard quickstart --write so the SDK can create a runnable starter file directly
• add --output and --force for safe local file creation and explicit overwrite behavior
• update onboarding docs so the install-to-first-run path can move from printed snippet to actual file in one command
• add proof artifacts under proof/quickstart-write-flow/

Why This Matters

• reduces copy-paste friction in the highest-priority onboarding path
• gives coding agents and humans a deterministic way to materialize a starter file locally
• keeps the first-run flow local-first, auditable, and zero-dependency

Scope

• sdk/agentguard/quickstart.py
• sdk/agentguard/cli.py
• sdk/tests/test_quickstart.py
• README.md
• docs/guides/coding-agents.md
• examples/starters/README.md
• sdk/PYPI_README.md
• proof/quickstart-write-flow/*

Non-goals

• no dashboard changes
• no new dependencies
• no new frameworks or hosted features
• no release cut

Proof

• python -m ruff check sdk/agentguard/cli.py sdk/agentguard/quickstart.py sdk/tests/test_quickstart.py
• PYTHONPATH=<repo>/sdk python -m pytest sdk/tests/test_quickstart.py -v
• PYTHONPATH=<repo>/sdk python scripts/sdk_preflight.py
• PYTHONPATH=<repo>/sdk python -m pytest sdk/tests -v --cov=agentguard --cov-report=term-missing --cov-fail-under=80
• python -m bandit -r sdk/agentguard -s B101,B110,B112,B311 -q

Saved artifacts:

• proof/quickstart-write-flow/raw-output.txt
• proof/quickstart-write-flow/openai-output.txt
• proof/quickstart-write-flow/overwrite-refusal.txt
• proof/quickstart-write-flow/agentguard_raw_quickstart.py
• proof/quickstart-write-flow/openai/agentguard_openai_quickstart.py

Notes

• This machine has an editable agentguard47 install outside this worktree, so local Python validation was run with PYTHONPATH pinned to sdk/ in this branch to ensure the tests and CLI exercised the PR code.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c0c3e18ad8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds a local-first “materialize a starter file” path to the AgentGuard SDK CLI so users (and coding agents) can go from install → runnable file with one command, reducing copy/paste friction while keeping overwrite behavior explicit.

Changes:

• Extend agentguard quickstart to support --write, --output, and --force, including updated “next commands” output for written files.
• Add unit tests covering file creation, overwrite refusal/force behavior, and CLI integration.
• Update onboarding docs/READMEs and add proof artifacts for the new flow.

Reviewed changes

Copilot reviewed 11 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sdk/agentguard/quickstart.py	Implements --write flow, file writing, and updated rendering for written starters.
sdk/agentguard/cli.py	Wires new quickstart flags into argparse and passes through to run_quickstart.
sdk/tests/test_quickstart.py	Adds tests for write/create/refuse/force overwrite and CLI writing behavior.
README.md	Documents the new --write/--output/--force onboarding path.
sdk/PYPI_README.md	Mirrors README onboarding updates for PyPI.
docs/guides/coding-agents.md	Adds guidance for generating starter files in-place via --write.
examples/starters/README.md	Updates suggested flow to include quickstart --write.
proof/quickstart-write-flow/raw-output.txt	Captures proof output for raw quickstart write flow.
proof/quickstart-write-flow/openai-output.txt	Captures proof output for OpenAI quickstart write flow.
proof/quickstart-write-flow/overwrite-refusal.txt	Captures proof output for overwrite refusal behavior.
proof/quickstart-write-flow/agentguard_raw_quickstart.py	Saved generated raw starter file artifact.
proof/quickstart-write-flow/openai/agentguard_openai_quickstart.py	Saved generated OpenAI starter file artifact.
PR_DRAFT.md	Draft PR narrative + validation commands and artifact listing.
MORNING_REPORT.md	Summary of work completed + validation notes.