# Repository Guidelines

Atlan Application SDK is a Python library for building applications on the Atlan platform.

Package manager: `uv` (task runner via `poe` in `pyproject.toml`).

Non-standard commands used across the repo:
- `uv sync --all-extras --all-groups` (full dev/test deps)
- `uv run poe start-deps` (local Dapr + Temporal)
- `uv run poe generate-apidocs` (MkDocs + API docs)
- `uv run pre-commit run --files <file>` (run pre-commit on specific file)
- `uv run pre-commit run --all-files` (run pre-commit on all files)

**IMPORTANT**: Always run pre-commit checks before committing. CI will fail if pre-commit checks fail.

**IMPORTANT**: For Dockerfile or dependency changes, run security scans (`trivy`, `grype`) before pushing. See `docs/standards/build-security.md`.

**IMPORTANT**: Never add or edit `CHANGELOG.md` entries manually. Changelog updates are generated by CI.

**IMPORTANT**: In GitHub Actions, do not inline shell that contains conditional logic (`if`/`else`, loops, `case`). Extract it into a script under `.github/scripts/` (Python, with a pytest in `.github/scripts/tests/`, run by the `CI script tests` workflow) and have the workflow `run:` call that script. Keep inlined `run:` blocks to straight-line commands. Rationale: branching logic in YAML can't be regression-tested. See `docs/standards/ci.md`.

**Commit Rules**:
- Never add Co-Authored-By lines to commits
- Follow Conventional Commits format from `docs/standards/commits.md`

**Confidentiality**:
- Never include customer names, tenant names, run IDs, or any other
  customer-identifiable information in code, comments, docstrings, commit
  messages, or PR descriptions. Reference incidents generically
  ("a production RCA", "a prior incident") — not by the customer or
  run involved.

**Path Semantics (ObjectStore)**:
- Key and prefix params for ObjectStore APIs accept either `./local/tmp/...` workflow paths or object-store keys like `artifacts/...`; the SDK normalizes these internally.
- Local file params remain local paths: `upload_file(key, local_path)` and `download_file(key, local_path)` — `key` is an object-store key (normalised internally); `local_path` is a local filesystem path and is never treated as an object-store key.

Where to look next (progressive disclosure):
- `docs/agents/project-structure.md` — quick map of key directories.
- `docs/agents/dev-commands.md` — setup and repeatable workflows.
- `docs/agents/coding-standards.md` — formatting, logging, exceptions, performance.
- `docs/agents/testing.md` — test command, coverage config, test layout.
- `docs/agents/commits-prs.md` — commit format and PR expectations.
- `docs/agents/docs-updates.md` — which conceptual docs to update with code changes.
- `docs/agents/review.md` — code review checklist.
- `docs/agents/deepwiki.md` — DeepWiki MCP setup and when to verify SDK details.
- `docs/standards/build-security.md` — image hierarchy, security scanning, Dapr setup.
- `docs/standards/v3-readiness.md` — v3 cutover checklist; use when reviewing app repos for v3 compliance.
- `docs/standards/env-vars.md` — process for removing/renaming env vars; add the old name to `_REMOVED_ENV_VARS` so users get a startup warning.
- `docs/standards/ci.md` — CI authoring: no inlined conditional shell; put logic in tested `.github/scripts/` scripts.
- `docs/agents/sdk-capabilities.md` — canonical capability manifest: every public symbol with import path, signature, summary, and all typed contracts. Generated by `.claude/skills/capability-manifest`; run `/capability-manifest` to refresh.
