Frequently asked questions
Setting up an Instruction Hub
Section titled “Setting up an Instruction Hub”Can we use an Instruction Hub without deploying an analyzer?
Section titled “Can we use an Instruction Hub without deploying an analyzer?”Yes. Publish and install your instructions with trace_ingestion.enabled: false, which is the default. That workflow does not require a worker, database, bucket, or model-provider credentials. See Set up your Instruction Hub.
Do we have to move every AGENTS.md or CLAUDE.md into the hub?
Section titled “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; it does not automatically turn them into shared skills. See Migrate existing instructions.
What does pig scan import automatically?
Section titled “What does pig scan import automatically?”It imports skills from .agents/skills, .claude/skills, and .cursor/skills, and supported root or Cursor MCP configuration. Other instruction layouts and asset kinds need a reviewed manual migration. Scan one source at a time and inspect the diff, because an existing destination asset with the same ID can be replaced. The migration guide covers inventory, naming conflicts, and pilot rollout.
Why is the pig plugin required?
Section titled “Why is the pig plugin required?”It is the canonical home for the toolchain-managed update skill and optional collection integration. It can also contain shared assets. Keep pig in stable_plugins, and organize additional instructions into plugins such as Acme’s docs and dev. See Key concepts.
Can we publish from GitLab?
Section titled “Can we publish from GitLab?”Yes. Hub publishing supports GitHub Actions and GitLab CI. Agent installation support still varies: test the team’s actual desktop importer, particularly Cursor with a GitLab repository. The current analyzer’s hub binding and remediation integration require GitHub and a main branch. See Publish and install plugins.
Agents and session data
Section titled “Agents and session data”Which agents does PIG support?
Section titled “Which agents does PIG support?”The toolchain builds instructions for Claude, Codex, Cursor, and Gemini. Native trace ingestion supports Claude Code, Claude Desktop, and Codex. These are separate capabilities; building a Cursor or Gemini plugin does not enable native collection for it. See Supported agents.
What leaves an enrolled host?
Section titled “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 plus findings and evidence summaries, which can describe session details. See Trust and data model.
Will enrolling a host upload its old sessions?
Section titled “Will 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. Subsequent collection resumes from the position recorded in the upload ledger. Agree on pilot hosts and repositories before enrollment, then verify a new session. See Enroll your hosts.
Does disabling trace ingestion delete data?
Section titled “Does disabling trace ingestion delete data?”No. After publishing and refreshing installed plugins, the new release no longer includes managed collection hooks. Older installed versions keep their hooks until refreshed. Previously stored traces, findings, and the analyzer deployment remain. Manage their retention separately. See Trust and data model.
Deployment and updates
Section titled “Deployment and updates”What does the analyzer need to run?
Section titled “What does the analyzer need to run?”The current service needs 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 a verified GitHub hub repository with a main branch. Private repositories need read credentials. Start with Plan your deployment.
Can we deploy on Azure or Google Cloud?
Section titled “Can we deploy on Azure or Google Cloud?”Azure and Google Cloud are experimental in 0.3.0. The first release targets AWS/EKS clean installation and canonical trace analysis through the Dashboard. The evaluation guides use native Blob Storage on Azure and Cloud Storage on Google Cloud; their availability does not establish equivalent cloud acceptance. Terraform prepares infrastructure before the common Helm bootstrap. See the AWS, Azure, and GCP guides for their prerequisites and configuration.
Does the trace analyzer update automatically?
Section titled “Does the trace analyzer update automatically?”The trace analyzer updates automatically to stable releases by default. You can pause updates or pin a release. The supervisor coordinates application and schema updates. Operators apply required infrastructure changes through Terraform, including changes to databases, storage, cloud identities, and networking. See Manage updates and recovery.
If your team needs to schedule and apply every upgrade, choose manually managed Helm during installation.
Does a healthy pod mean analysis is working?
Section titled “Does a healthy pod mean analysis is working?”No. Verify that an enrolled host can upload, the trace is stored, and analysis completes. A completed analysis may produce no finding. The health endpoint alone does not establish the entire path. See Observability.
How do we verify plugin installation across our hosts?
Section titled “How do we verify plugin installation across our hosts?”Track rollout through your release and enrollment records. Follow the plugin installation checks on each host. Enrollment and trace collection do not prove that every plugin is installed and loaded.
Findings and changes
Section titled “Findings and changes”Does PIG merge instruction changes automatically?
Section titled “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 publishing a new hub release. See Remediate findings.
Does every finding need an instruction change?
Section titled “Does every finding need an instruction change?”No. A finding may require work on a tool, integration, or external system. Review the explanation and evidence before deciding who should act. See Understand findings.
Which systems use GitHub credentials?
Section titled “Which systems use GitHub credentials?”The analyzer can use a configured read token for a private hub. Promptless uses the connected GitHub integration to coordinate issues and provides repository-scoped credentials for remediation tasks. Keep these credentials separate from deployment and per-host credentials. See Trust and data model.
Get support
Section titled “Get support”Contact help@gopromptless.ai for setup or deployment help. Include the affected component, deployment or hub version, and the step that failed. Share redacted diagnostics rather than credentials or raw session transcripts.