Projects and context

A Polaris project connects the agent to your data. Each project is a folder, and the files in it are the context: everything the agent reads before it answers. Good context is what makes answers correct and repeatable.

The project folder

pda init creates this layout:

my-project/
├── pda_config.yaml     # databases, models and integrations
├── RULES.md            # the main instructions for the agent
├── .pdaignore          # files the agent must not see
├── databases/          # table docs, written by pda sync
├── docs/               # business docs (your own, or synced from Notion, Confluence, Obsidian)
├── repos/              # code repositories, for example a dbt project
├── semantics/          # semantic layer docs, written by pda sync
├── agent/
│   ├── skills/         # task instructions the agent can load
│   ├── prompts/        # optional system prompt overrides
│   ├── mcps/           # outbound MCP servers for the agent
│   └── tools/
└── tests/              # questions with known answers, for pda test

File or folder	Read more
pda_config.yaml	pda_config.yaml
RULES.md	RULES.md
.pdaignore	.pdaignore
databases/	Databases
semantics/	Semantic layer
agent/skills/	Skills
tests/	Tests

How the agent uses the context

• RULES.md is added to every chat.
• The agent searches and reads the other files as it needs them: table docs to find columns, business docs for definitions, skills for specific tasks.
• Files listed in .pdaignore are hidden from it.

The lifecycle

1. Set up. Install the CLI, run pda init, and configure your databases.
2. Sync. Run pda sync to write table docs from your databases. See Synchronization.
3. Write rules. Describe the business, the key tables and the metrics in RULES.md.
4. Test. Write test questions with known answers and run pda test. See Tests.
5. Improve. Read failed tests and bad ratings, and fix the context. See Context engineering.
6. Deploy. Send the folder to your team’s Polaris with pda deploy. See Deploy context.

Keep the project folder in Git, so every change is reviewed and can be rolled back.

The example project

The example project, polaris-epigenomics, connects to the example data. Its RULES.md covers the cohort, the table grain and keys, join pitfalls, and how to compute mutation, copy number, expression, methylation and survival metrics. It has 24 tests across TCGA, Open Targets, IDC and cross-source questions.

Context on a shared deployment

On a shared Polaris deployment, the project context comes from Git and is deployed by the people who maintain the project. The File Explorer in Settings lets admins and context admins browse it. Edits made there are saved as personal drafts and do not change what the agent reads. To change the context, change the files in Git and deploy them.