This page answers questions about setting up an Instruction Hub, collecting agent sessions, deploying and updating the analyzer, and acting on findings. Each answer links to the page with the full procedure or explanation.
| Question | Answer | More information |
|---|
| Can we use an Instruction Hub without deploying an analyzer? | Yes. Publish and install your instructions with trace_ingestion.enabled: false, the default. That workflow needs no worker, database, bucket, or model-provider credentials. | Set up your Instruction Hub |
Do we have to move every AGENTS.md or CLAUDE.md into the hub? | No. Move reusable instructions into shared hub assets, and keep repository-specific context beside the project it describes. pig scan records root context files in its inventory but doesn’t turn them into shared skills. | Migrate existing instructions |
What does pig scan import automatically? | Skills from .agents/skills, .claude/skills, and .cursor/skills, plus supported root or Cursor MCP configuration. Other layouts and asset kinds need a reviewed manual migration. Scan one source at a time and inspect the diff, because the scan can replace an existing asset with the same ID. | Migrate existing instructions, for inventory, naming conflicts, and pilot rollout |
Why is the pig plugin required? | It’s the canonical home for the toolchain-managed update skill and the optional collection integration, and it can hold shared assets. Keep pig in stable_plugins, and organize other instructions into plugins such as Acme’s docs and dev. | The required pig plugin |
| Can we publish from GitLab? | Yes. Hub publishing supports GitHub Actions and GitLab CI. Agent installation support varies, so test your team’s desktop importer, particularly Cursor with a GitLab repository. The analyzer’s hub binding and remediation require GitHub and a main branch. | Publish and install plugins |
| Question | Answer | More information |
|---|
| Which agents does PIG support? | The toolchain builds instructions for Claude, Codex, Cursor, and Gemini. Native trace collection is a separate capability: it supports Claude Code, Claude Desktop, Codex, and, with analyzer 0.3.3 or later, Cursor desktop sessions. Building a Gemini plugin doesn’t enable collection for Gemini. | Supported agents |
| What leaves an enrolled host? | The collector uploads native session records and related collection metadata to your analyzer. Your configured model provider receives analysis input. Promptless receives trace status, findings, and evidence summaries, which can describe session details. | Trust and data model |
| Does enrolling a host upload its old sessions? | It can. When a discovered native source has no acknowledged upload position, collection starts from the beginning and can upload existing session history. Later collection resumes from the position in the upload ledger. Agree on pilot hosts and repositories before enrollment, then verify a new session. | Enroll your hosts |
| Does disabling trace ingestion delete data? | No. A release published with trace ingestion disabled leaves out the managed collection hooks, and each host keeps its hooks until it refreshes its installed plugins. Stored traces, findings, and the analyzer deployment remain, so manage their retention separately. | Trust and data model |
| Question | Answer | More information |
|---|
| What does the analyzer need to run? | A Kubernetes deployment, PostgreSQL, native object storage, a Promptless deployment token, and network access between those systems. Analysis also needs a configured model provider and instruction repositories selected in PIG Settings. Each selected repository is a GitHub repository with a main branch. | Plan your deployment |
| Can we deploy on Azure or Google Cloud? | Azure and Google Cloud are experimental. The current stable release, PIG 0.3.6, targets only AWS (EKS). The Azure and Google Cloud guides are for evaluation. On every cloud, Terraform prepares the infrastructure before the common Helm bootstrap. | AWS, Azure, and GCP guides, for prerequisites and configuration |
| Does the trace analyzer update automatically? | Yes. By default it updates to stable releases, and you can pause updates or pin a release. The supervisor coordinates application and schema updates. Operators apply required infrastructure changes, such as databases, storage, cloud identities, and networking, through Terraform. | Manage updates and recovery |
| Can we schedule and apply every upgrade ourselves? | Yes. Choose manually managed Helm during installation. | Manually managed Helm |
| Does a healthy pod mean analysis is working? | No. The health endpoint doesn’t cover the whole path. Verify that an enrolled host can upload, the trace is stored, and analysis completes. A completed analysis can produce no finding. | Observability |
| How do we verify plugin installation across our hosts? | Track rollout through your release and enrollment records, and run the plugin installation checks on each host. Enrollment and trace collection don’t prove that every plugin is installed and loaded. | Publish and install plugins |
| Question | Answer | More information |
|---|
| Does PIG merge instruction changes automatically? | The documented workflow produces a proposed pull request for your team to review. Apply your repository’s checks and merge controls before you publish a new hub release. | Remediate findings |
| Does every finding need an instruction change? | No. A finding can call for work on a tool, integration, or external system. Review the explanation and evidence before you decide who acts on it. | Understand findings |
| Which systems use GitHub credentials? | Promptless gives the analyzer GitHub App tokens, scoped to Contents read, for the instruction repositories selected in PIG Settings. Promptless also uses the connected GitHub integration to coordinate issues, and provides repository-scoped credentials for remediation tasks. Operators don’t configure a GitHub token for the analyzer. | Select instruction repositories |
Email help@gopromptless.ai for setup or deployment help. Include these details:
| Detail | What to send |
|---|
| Affected component | The hub toolchain, an enrolled host, or the analyzer deployment |
| Version | The deployment or hub version |
| Failed step | The step that failed |
| Diagnostics | Redacted diagnostics. Don’t send credentials or raw session transcripts. |