Skip to content

docs: improve README onboarding and usage #3

Description

@egdev6

Problem

The current README documents the package but does not provide enough visual hierarchy or progressive onboarding for new users to understand installation, the plan/apply workflow, safety boundaries, and verification quickly.

Proposed solution

Redesign the README with a clearer visual hero, navigation, concise quick start, copy-paste plan/apply examples, capability and safety tables, release guidance, and a repository map. Keep every command and claim aligned with the actual Pi package layout and implementation.

Acceptance criteria

  • Installation uses the immutable v1.0.0 Git package reference.
  • Quick start explains the conversational Pi workflow before low-level executor commands.
  • Plan and apply examples use Pi's actual project-local Git package path.
  • Capabilities and safety guarantees match the skill, schema, and implementation.
  • Release behavior describes independent tag and GitHub Release checks.
  • Local links and document anchors resolve.
  • Existing tests continue to pass.

Scope and non-goals

This is a documentation-only change to README.md. It does not modify package behavior, workflows, tests, release artifacts, or npm publication settings.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationstatus:approvedApproved for implementation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions