[promptless]

Requested by: Adit Chandra

Proposed changes

Completes the self-hosted PIG trace analyzer installation docs for the current stable release, PIG 0.3.6 (stable catalog, 0.3.6 manifest), so an operator can go from prerequisites to a verified first trace and analysis on customer-owned AWS infrastructure. Entry point: Deploy trace analysis.

Sources: pig-deploy release commit db79db5 (examples, schemas/pigdeployment-spec.json, charts/pig-supervisor, CONTRACT.md, STORAGE.md, AWS example), the published pig-supervisor-0.3.6.tgz, analyzer source 625624a (the 0.3.6 analyzer commit), pig-toolchain main 4c02abf, and the PIG dashboard on Promptless/promptless main b46d4e7.

Install path (plan-your-deployment, deploy-on-aws, deploy-the-analyzer-worker)

• Platform support table for 0.3.6 (Kubernetes ≥ 1.30, PostgreSQL 15–18, exactly one native object store, schema revision 5). AWS is the published target; the page says its release record does not include live end-to-end acceptance, and Azure/GCP stay experimental.
• Ordered installation path from planning through verification, and fuller prerequisites (sizing, workload identity, DNS/TLS, cloud-agent public endpoint, model quota).
• Analyzer registration with the current Dashboard labels and the working URL https://app.gopromptless.ai/pig/settings/workers (the old /instruction-hub/... link no longer resolves).
• New step 1: in one working directory (PIG_RELEASE_DIR), download release.json, SHA256SUMS, the bootstrap chart, and the Terraform archive. Verify them against the stable catalog; the expected 0.3.6 digests are listed. The checksum commands work with GNU sha256sum or macOS shasum -a 256.
• Cloud guides extract Terraform from the verified archive, save deployment-configuration.json in $PIG_RELEASE_DIR, return there before resuming Helm step 2, use -backend-config with encrypted, locked remote state and -lockfile=readonly, and pass the DB password as TF_VAR_postgres_password. AWS guide maps deployment_configuration to the DSN, CA ConfigMap, ServiceAccount annotation, and storage block.
• Secrets and CA: pig-credentials (install-token, postgres-dsn, model-api-key for API-key auth), ConfigMap pig-postgres-ca/ca.pem, optional pig-migration owner DSN via spec.storage.postgres.migrationDsnSecretRef, and the least-privilege role grants (from STORAGE.md) on the PostgreSQL page.
• Complete bootstrap values for ingress-nginx with a TLS Secret and for AWS ALB with ACM, including the required ingress.serviceName/hostname/ingressClassName (the earlier watchNamespace-only example fails to render).
• A complete PIGDeployment with release channel, pin, and pause explained; Ready=True vs the Acceptance condition; DNS and HTTPS checks from the hosts' network (/healthz plus an unauthenticated policy request that must return 401); repository selection with the live Create Repo Issues / Propose Remediations labels and permissions; and a separate Enable trace analysis step for the existing Trace analyzer switch.
• Ownership among Terraform, Kubernetes config/GitOps, the pig-supervisor Helm release, and the supervisor, consolidated in gitops-ownership.

Request limits and routes (networking-and-identity, manual-helm, configuration-reference)

• Replaces "at least 10 MiB / nginx 10m" with both real limits: the collector's largest encoded request is 10 MiB (pig-toolchain MAX_TRANSPORT_BATCH_BYTES), and the analyzer accepts encoded bodies up to 2 × PIG_MAX_TRACE_BATCH_BYTES + 64 KiB (_native_trace_transport_body_limit, about 512 MiB at the 256 MiB decoded default). Examples use proxy-body-size: "256m", which matches the pig-deploy contract and fits both limits. Adds collector timeout guidance (10 s per read).
• Method/path table for the five released routes, header forwarding (Authorization, cloud X-Promptless-Producer-Token), HTTPS without redirects, and public endpoints for cloud agents.

Enrollment and verification (enroll-your-hosts, verify-your-deployment, agent-setup-guide, September changelog)

• Approval page moves to /pig/enroll. Adds a host-side upload check (collect --include-active → trace_upload_complete). Fixes the verification link.
• Removes the enroll --device instructions, troubleshooting rows, agent-guide step, and the September changelog entry: device-code enrollment is not in the released toolchain (it exists only on an unmerged pig-toolchain branch).
• Verification SQL now checks the same session end to end, matching the supervisor's acceptance check: enrolled host (agent_hosts), written object, succeeded run of the current revision (source_fingerprint = analysis_source_sha256), and hosted acknowledgement (projection_published_revision >= projection_revision). Adds the Dashboard Traces page checks, including the zero-findings text. repository_sha stays: the 0.3.6 analyzer still stores and logs it.

Carried and folded work

• Includes the commits of docs: Use PIG names for 0.3.5 and add the supervisor bootstrap for 0.3.4 installations #1129 (0.3.5 pig Helm values, 0.3.4 supervisor bootstrap upgrade, 0.3.6 version strings) so one branch carries a consistent 0.3.6 install path. docs: Use PIG names for 0.3.5 and add the supervisor bootstrap for 0.3.4 installations #1129's remaining diff against this branch is empty.
• Folds in docs: Note that PIG updates and deployment checks pass while analysis is disabled #1153 (updates complete while analysis is disabled), Document analyzer check-in staleness for PIG verification #999 (15-minute staleness), and the networking/verification wording from docs: Changelog and deploy-doc cross-references for the analyzer installation-identity workflow #1033.
• October changelog: subtitle now names 0.3.6, plus one entry for 0.3.6 and the updated install guide.

Separate CI fix (own commit)

• tests/smoke/smoke.spec.ts: the Agent Score landing smoke test failed on main (43570d81) as well as on this PR, because Agent Score Agent Score landing: plain copy, animated hero with agent logos, port rejection, leaderboard trim #1155 and Trim the Agent Score hero and scan progress copy #1159 changed the page. The test now checks the current headline, the CLI example with --skip-checks, and the afdocs link, and asserts that the removed methodology section stays absent. No coverage was dropped.

Remaining dependencies and limits

• No customer deployment was run. Cloud lifecycle behavior (upgrades, self-update, recovery) and live analysis acceptance for 0.3.6 artifacts are unverified in the release record, and the docs do not claim otherwise.
• Not documented because they have not shipped: device-code enrollment (pig-toolchain), the trace-backlog choice when enabling analysis (Promptless/promptless#5093, open; docs PR Let admins choose the trace backlog when enabling analysis #1013), and per-hub analyzer URLs (pig-toolchain docs: Remove ReadMe API references from documentation platforms #91).
• The cloud agent page (capture-cloud-agent-traces) arrives with docs: Document cloud agent trace capture for PIG 0.3.5 and later #1125. This PR does not link to it, so it has no dependency on docs: Document cloud agent trace capture for PIG 0.3.5 and later #1125.

Validation

• Downloaded the v0.3.6 release assets. The step 1 checksum check passes with both sha256sum and shasum -a 256. release.json matches the catalog digest a4eafe78…af977, and the chart matches 5fc16c87…b74b (the OCI pull digest also matches the manifest). Ran the page's step 1 commands exactly as written.
• helm lint and helm template (Helm 3.18.6) on the published 0.3.6 chart pass for both copy-paste bootstrap value sets. The rendered Ingress has the five exact paths in pig, and a watchNamespace-only file fails as expected.
• The PIGDeployment example validates against the 0.3.6 schemas/pigdeployment-spec.json and the chart CRD, both as written and with migrationDsnSecretRef enabled; spec.endpoint is rejected.
• terraform init -backend=false -lockfile=readonly and terraform validate (1.11.4) on the 0.3.6 AWS example from the verified archive pass.
• npm run test:smoke passes 28 of 28 locally; before the test fix it failed on test 24 here and on main. test:search:build passes 14 of 14.
• npm run build passes. Internal links and anchors on all changed pages resolve in the built site: 1,084 links checked, 0 broken. lint:md and lint:frontmatter pass. Vale reports no new findings.

Checklist

• Instructions and examples match the current product behavior.
• Links and image references are valid.
• Changed pages render correctly.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
promptless-docs	Ready	Preview	Oct 15, 2026 10:36pm UTC