v0.13.0

Upgrade notes

• Redacted JSON plans also redact comments and role configuration values. pgroles diff --format json (single manifests and pgroles.bundle_plan.v2 bundles) previously replaced only password values. It now also replaces role comments and config values with "[REDACTED]", as --format markdown does; keys and shape are unchanged. --format sql still prints comments and configuration values and never prints password values. Read comment and configuration values from the manifest rather than from diff JSON. (#236)
• pgroles-core has a default passwords feature. It gates the scram module, diff::resolve_passwords, diff::inject_password_changes, and their SCRAM dependencies. Default builds are unchanged. Crates that set default-features = false must enable passwords to keep these APIs; parsing, planning, SQL rendering, visualization, authoring, and review artifacts remain available without it. (#236)
• Browser authoring endpoints limit policy YAML to 1 MiB. authoring::validate_policy and authoring::compile_policy return a policy_too_large diagnostic above authoring::MAX_POLICY_YAML_BYTES, and the explorer's analyze applies the same limit. pgroles validate, diff, and apply, bundles, the operator, and authoring::prepare_policy have no byte limit; manifest entry bounds still apply everywhere. Rust code that matches ManifestError exhaustively needs an arm for the new YamlTooLarge variant. pgroles_cli::ValidatedManifest is now an alias of authoring::PreparedPolicy, with the same fields. (#236, #241)
• New diff review flags need this release. --review-out, --target-label, --policy-commit, and --executor-role are usage errors in 0.12.0 and earlier, and usage errors exit with code 2 like drift. Pin the image or binary version in CI jobs that use them, and accept exit code 2 as drift only when the review file was written, as the updated PR-comment recipe does. (#236, #241)
• Routine grant targets are resolved during inspection. An ensure: present rule for a function or procedure that does not exist, a bare name that matches several overloads, or a named-argument signature spelled differently from the catalog now fails inspection of that policy, listing the input-type signatures to use; the operator reports InvalidRoutineTarget. Previously diff planned a GRANT that failed on apply. pgroles generate now writes input-type signatures such as process(integer); policies generated by earlier versions keep working. (#239)

Added

• Plan explorer. The documentation site has a browser explorer that shows a policy's ordered plan, executor authority, and findings against a sanitized snapshot, and opens diff --review-out files, without connecting to a database. (#236, #241)
• pgroles diff --review-out writes a sanitized recorded review from the same inspection and planning run as the normal output, with any --format. The file records the ordered changes, bundle attribution, SQL preview, phase authority, findings, lifecycle-managed scope (external: true roles excluded), tool and PostgreSQL versions, capture time, policy content digest, and preflight evidence that names the targeted checks performed and the changes they did and did not cover. --target-label names the environment and rejects values containing ://; --policy-commit records the source revision; --executor-role records an intended executor without verifying it. Password values, role configuration values, and comments are omitted with explicit omission records, and the whole SQL preview is omitted when any change carries them. The artifact never reads password.from_env variables. (#236, #241)
• Review fingerprints link reports to files. With --review-out, the Markdown report ends with the artifact's review fingerprint, and stderr prints the file path and the same fingerprint. If the file cannot be written, diff still prints the report, then exits with code 1, including with --no-exit-code. (#241)
• Policy authoring API. pgroles_core::authoring::prepare_policy is the parse, expansion, and normalization step shared by the CLI and explorer. validate_policy and compile_policy accept a versioned PolicyRequest (pgroles.policy.v1) and return structured diagnostics with stable codes, manifest field paths, and syntax byte ranges; compilation also returns the expanded policy and normalized desired graph. Neither resolves password sources. diff::plan_changes is the canonical planner for retirements, reconciliation mode, external roles, and preserved grants, shared by the CLI, operator, and explorer. (#236)
• Review artifact contract. pgroles_core::review_artifact types implement Deserialize and JsonSchema, and parse_review_artifact checks the size limit, schema version, change-index partition, reachability deltas, and fingerprint. The JSON Schema is generated to docs/public/generated/review-artifact.schema.json and served with the documentation. (#241)
• Row-level security lesson. The Acme PostgreSQL course adds an advanced lesson between membership mechanics and the security review. Its labs use PostgreSQL to demonstrate default deny, tenant row visibility, rejected writes, owner and FORCE behaviour, bypass roles, and policy composition. Six cumulative chapter policies preserve earlier access. (#236)

Changed

• diff no longer computes password verifiers. Every diff format redacts password values, so plans carry declared password intent. sql, json, and summary still fail when a declared password.from_env variable is unset; markdown does not read them. Output is unchanged. (#241)
• Documentation navigation separates Docs, Learn PostgreSQL, and Explorer. A canonical page registry drives sidebars, breadcrumbs, and reading sequences; product docs are grouped by task; the homepage routes to trying pgroles, adopting a database, and reviewing a plan. New planning and recorded-review guides replace sections of the CI/CD guide, whose anchors keep working. (#237)

Fixed

• Routine grants no longer churn on equivalent signatures. Function and procedure grants are keyed by input types across inspection, planning, export, and revoke preflight, so process(integer) and the catalog's process(job_id integer) no longer produce a grant followed by a revoke of the same routine. PostgreSQL type aliases such as int2 resolve to one target, and opposite present and absent rules for that target fail before apply. (#239)

Documentation

• The documentation site has full-text search across Docs and Learn PostgreSQL, a mobile "On this page" menu, linked breadcrumbs, and a footer naming the source commit and latest release. (#238)
• The PR-comment CI recipe pins an image version that supports --review-out, runs the container as the runner user so it can write into the workspace, removes stale review files, and accepts exit code 2 as drift only when the review file exists. It reads the report as data rather than interpolating it into JavaScript, uploads both files, and bounds comment size. A documentation test runs the recipe against a stubbed container. (#236, #241)
• Correct the Acme course's reset-sensitive instructions, evidence cards, membership direction and options, ADMIN self-grant implications, creator-specific default privileges, and multi-database retirement guidance. Capstone repairs are optional challenges. (#236)
• The pgroles-policy skill documents the recorded-review workflow and links to the published documentation instead of repository paths, which are absent from release archives. (#236, #241)