endorlabs 0.2.0__tar.gz

endorlabs-0.2.0/.cursor/rules/agent-knowledge-authoring.mdc

@@ -0,0 +1,31 @@
+---
+description: Author or update agent knowledge under agent-knowledge/ using the schema-driven authoring guide.
+globs: agent-knowledge/**
+alwaysApply: false
+---
+
+# Agent knowledge authoring
+
+When editing files under `agent-knowledge/`, follow the canonical authoring spec:
+
+- [agent-knowledge/schema/README.md](../../agent-knowledge/schema/README.md) — portable frontmatter, `endorlabs.catalog` extension, **skill composition and handoffs**, rules, contracts, workflows.yaml
+- [agent-knowledge/schema/skill.schema.json](../../agent-knowledge/schema/skill.schema.json) — machine validation
+
+For multi-step or narrow-scope skills, document **Scope**, **Related skills** (with reciprocal links on peers), and optional **Optional stops** / routing tables — see [Skill composition and handoffs](../../agent-knowledge/schema/README.md#skill-composition-and-handoffs). Every skill id must use the **`endor-*`** prefix (see [schema/README.md](../../agent-knowledge/schema/README.md)).
+
+After changes, run `uv run python devtools/sync_agent_knowledge.py`. Shipped `SKILL.md` files must contain **only** portable frontmatter (`name`, `description`, optional `disable-model-invocation`).
+
+## Path consistency (tests and docs)
+
+When renaming a skill directory, script, or cited runtime path, **keep tests and docs aligned in the same change**:
+
+- Grep `tests/` for the old skill id or script path; update any `candidate_paths` loaders (see `tests/unit/tooling/scripts/test_*` for precedent).
+- Update skill body examples (`.cursor/skills/endor-<name>/…` in commands) and cross-links under `agent-knowledge/skills/`.
+- Run sync so `src/endorlabs/agent_knowledge/` matches authoring; integration tests may assert materialized paths under `.endorlabs-context/sdk/skills/`.
+- Do **not** add shared test helper modules for path resolution — inline loaders in the tests that need them are the contract.
+
+## Tests (manifest and drift)
+
+- **Drift gate:** `tests/unit/platform/context/test_agent_knowledge_drift.py` runs `devtools/sync_agent_knowledge.py --verify`. That is the authoritative check that authoring, shipped bundle, INDEX, workflows, and `MANIFEST.json` stay aligned.
+- **Do not hardcode skill or workflow counts** in unit tests (same principle as [docs-skillbase-consistency.mdc](docs-skillbase-consistency.mdc): no brittle “complete inventory” assertions). Adding or removing a skill should not require bumping a magic number.
+- Prefer **structural** manifest checks: unique ids, required fields, on-disk paths under `agent_knowledge_dir()`, bootstrap `rule_ids` matches `rules[]`, and targeted presence/absence for the change under test (e.g. workflow row with `skill: null`).

endorlabs-0.2.0/.cursor/rules/docs-skillbase-consistency.mdc

@@ -0,0 +1,22 @@
+---
+description: Keep docs aligned with codebase and skillbase paths
+globs: **/*.{md,mdc}
+alwaysApply: false
+---
+
+# Docs and Skillbase Consistency
+
+When editing repository docs or rules, keep documentation references aligned with the current repo layout and generated sources of truth.
+
+- Prefer `agent-knowledge/skills/...` links/paths in git-tracked docs.
+- If `.cursor/skills/...` is mentioned, label it as the mirrored runtime path used by Cursor.
+- Do not maintain hardcoded "complete" resource inventories in hand-edited docs; point to `docs/generated-reference/resources.md` for the canonical current list.
+- Apply the same rule to **tests**: do not assert exact skill/workflow counts in `test_agent_knowledge.py`; use `sync_agent_knowledge.py --verify` (see `test_agent_knowledge_drift.py`) plus structural manifest checks.
+- Keep workflow and CLI inventory statements synchronized with:
+  - `src/endorlabs/workflows/__init__.py`
+  - `[project.scripts]` in `pyproject.toml`
+- For doc corrections, preserve OS-agnostic command examples where possible.
+- When editing skill playbooks, follow [agent-knowledge/schema/README.md — Skill composition and handoffs](../../agent-knowledge/schema/README.md#skill-composition-and-handoffs) for **Scope**, **Related skills**, and reciprocal peer links.
+- When renaming skills, scripts, or path examples, **maintain consistency with tests and docs**: grep `tests/` for the old id/path, update skill command examples and `MANIFEST.json` refs (via sync), and keep the three trees aligned (`agent-knowledge/skills/`, shipped `src/endorlabs/agent_knowledge/skills/`, mirrored `.cursor/skills/`).
+- **Doc placement:** tracked `docs/` is public-safe and durable — `docs/guides/` for SDK consumers, `docs/contributing/` for maintainers/release/CI. Do not commit session reports, readiness assessments, or implemented feature PR playbooks under `docs/`; use `.endorlabs-context/workspace/sessions/<user>/notes/` instead. No `docs/findings/` or tracked `*-draft.md` / `*-assessment.md`.
+- **Changelog:** breaking changes and user-notable **Added** entries go in [`docs/changelog.md`](../../docs/changelog.md) under **Unreleased**; PR intake in [`.github/pull_request_template.md`](../../.github/pull_request_template.md). At release, promote to `## X.Y.Z`. Do not add parallel `*-migration.md` files or duplicate breaking tables elsewhere.

endorlabs-0.2.0/.cursor/rules/endor-changelog.mdc

@@ -0,0 +1,95 @@
+---
+description: Record breaking changes and notable features in docs/changelog.md only; keep Unreleased high-signal; use PR intake block before merge.
+globs:
+  - src/endorlabs/**
+  - **/*.py
+  - **/.endorlabs-context/**
+  - agent-knowledge/**
+  - docs/**
+  - devtools/**
+alwaysApply: false
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-changelog.md
+x-endor-source-sha256: 4a624cbdd0073ab9eb26873faa56d06a5b0e02a8c03e98f0b22385c2e764ef8d
+---
+
+# Changelog (maintainer)
+
+**Canonical file:** [`docs/changelog.md`](../../docs/changelog.md)
+
+## What belongs in the changelog
+
+| Section | Include | Exclude |
+|---------|---------|---------|
+| **Breaking** | Removed CLI/API paths, renames, layout changes users must act on | Internal refactors, test-only changes |
+| **Added** | New `[project.scripts]` CLI, new `Client.<Kind>` / public API, shipped agent skills with distinct playbooks | Maintainer scripts, CI-only wiring, routine model regen |
+| **Changed** | Behavior or defaults that affect consumers without a hard break; optional release footnote when models align to a new OpenAPI snapshot | Doc-only edits unless user-visible |
+
+### Added — detail
+
+**Include when upgraders gain a new capability:**
+
+- New console script or workflow CLI (`pyproject.toml` → `[project.scripts]`).
+- New registry facade, operation, or public `endorlabs.*` helper consumers call.
+- New shipped skill under `sdk/skills/` (one bullet per skill id, or one grouped bullet listing ids).
+- New optional PyPI extra or contract behavior documented in `contracts.md`.
+
+**Prefer one grouped bullet** when landing several skills in one release: “Agent skills: `endor-foo`, `endor-bar` (shipped `MANIFEST.json`).”
+
+### Model sync / backend OpenAPI
+
+| Situation | Changelog |
+|-----------|-----------|
+| Regen only; same resources and ops | **Omit** (or one **Changed** footnote at release: “Models aligned to platform OpenAPI snapshot.”) |
+| New resources, ops, or create kwargs in generated reference | **Added** — name the resource or capability |
+| Removed resource, stricter validation, facade break | **Breaking** |
+| Payload tolerance / validation fixes callers saw | **Changed** |
+
+Detail stays in [`docs/contributing/docs-drift-workflow.md`](../docs/contributing/docs-drift-workflow.md) and `docs/generated-reference/` — do not replay every regen PR.
+
+### Skills / workflows
+
+- **New skill** → **Added** (or grouped).
+- **Skill playbook fix** → **Changed** only when behavior materially changes for agents/users.
+- **Workflow module without new console script** → usually omit unless it is the main upgrade reason.
+
+## PR intake (before merge)
+
+Copy into the PR description ([`.github/pull_request_template.md`](../../.github/pull_request_template.md)). When **user-facing**, append the **Summary** line to **`docs/changelog.md` → Unreleased** in the same PR.
+
+```markdown
+- [ ] Not user-facing → no Unreleased edit
+- [ ] User-facing → one bullet under Added | Changed | Breaking
+
+Section: Added | Changed | Breaking | none
+Summary: (one imperative sentence)
+Audience: sdk-user | agent-skill | both
+Migration: (Breaking only)
+```
+
+Optional structured fields: [`agent-knowledge/schema/changelog-intake.schema.json`](../schema/changelog-intake.schema.json) (reference only; not CI-gated).
+
+**PR title hints (triage, not auto-changelog):** `feat(cli): …` · `fix(sdk): …` · `chore(model-sync): …` (usually no Unreleased line).
+
+## Workflow
+
+1. Stage under **`## Unreleased`** while work lands on `main`.
+2. At release, rename **Unreleased** → **`## X.Y.Z`** (keep subsections Added / Changed / Breaking).
+3. Leave a fresh empty **Unreleased** (subsection headers only until the next entry).
+4. Link from product docs (e.g. [estate/README.md](../../docs/estate/README.md)) to **`docs/changelog.md`** — not duplicate migration files.
+
+**Release cut checklist** (see also [release-publishing.md](../../docs/contributing/release-publishing.md)):
+
+1. Collapse model-sync-only PRs into one **Changed** footnote or omit.
+2. Promote **Unreleased** → `## X.Y.Z`; reset **Unreleased** headers.
+3. Grep for removed CLI/API names; update durable docs to **current** behavior only.
+
+Do **not** auto-generate `docs/changelog.md` from `git log`.
+
+## Do not
+
+- Add `docs/**/*-migration.md` or long breaking tables outside the changelog.
+- Put session reports or readiness assessments in the changelog (use workspace `notes/`).
+- Duplicate the same breaking table in skills, contributing guides, and changelog.
+
+When you add a **Breaking** entry, grep for old names/paths and update durable docs ([`docs/estate/`](../../docs/estate/), skills) to describe **current** behavior only; point upgraders at the changelog.

endorlabs-0.2.0/.cursor/rules/endor-list-query-performance.mdc

@@ -0,0 +1,45 @@
+---
+description: Do not set page_size unless explicitly asked; scope and filter before raising max_pages.
+alwaysApply: true
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-list-query-performance.md
+x-endor-source-sha256: f421ebe7b623c25e9987e0b0b59b951e636ba2a3ca727e5140a4341d518952b5
+---
+
+# List query performance
+
+Guidance for SDK `list()` / `list_iter()` calls, workflow CLIs, and session scripts.
+
+## Scope first
+
+- Prefer **`Client(tenant="<child-or-leaf-namespace>")`** and **list without `traverse`**
+  when you only need resources in that namespace.
+- Use **`traverse=True`** from the tenant root only when you intentionally need the
+  whole hierarchy.
+
+A single `list(traverse=True)` minimizes round-trips; it does not guarantee a fast
+server-side plan for broad unfiltered queries.
+
+## Filters
+
+- Prefer **selective filters** that narrow rows before pagination.
+- **Filter** selects rows; **mask** trims returned fields — do not conflate them.
+- A non-empty **mask** returns **`dict`** rows, not Pydantic models.
+
+## Pagination
+
+- **Do not set `page_size`** unless the user explicitly asks. Rely on API/SDK defaults.
+  Very small `page_size` (especially `1`) can be pathologically slow on log-style resources
+  (`AuditLog`, `FindingLog`, `AuthenticationLog`, …).
+- **`max_pages`** caps client-side fetch depth — acceptable for bounding cost; it does not
+  replace selective `filter` or namespace scope.
+- For log resources, cap **`max_pages` only** and leave `page_size` unset.
+
+## Debugging slow lists
+
+1. Narrow to a **child namespace** without `traverse`.
+2. Add or tighten **`filter`** when supported.
+3. Compare with `endorctl api list` (same resource, namespace, filter, traverse).
+4. Use a shorter read timeout when iterating locally.
+
+See also `rules/endor-namespace-scoping.md` and `contracts/list-parameters.md`.

endorlabs-0.2.0/.cursor/rules/endor-local-context.mdc

@@ -0,0 +1,44 @@
+---
+description: Check gitignored .endorlabs-context paths explicitly; prefer local platform docs before the web; never print secrets.
+globs:
+  - src/endorlabs/**
+  - **/*.py
+  - **/.endorlabs-context/**
+  - agent-knowledge/**
+  - docs/**
+  - devtools/**
+alwaysApply: false
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-local-context.md
+x-endor-source-sha256: e395b9b272f410d52e9114c0afadee7f39d2e1d05338f89cbf42c47ebfcb1ee0
+---
+
+# Local context discovery
+
+When guidance references local context under gitignored paths, do not assume those
+files are absent because a broad search did not show them.
+
+## Check explicitly
+
+- `.endorlabs-context/`
+- `.endorlabs-context/context.json`
+- `.endorlabs-context/sdk/INDEX.md`
+- `.endorlabs-context/sdk/MANIFEST.json`
+- `.endorlabs-context/platform/openapi/openapiv2.swagger.json` (canonical OpenAPI)
+- `.endorlabs-context/platform/user-docs/`
+- `.env` (confirm variables exist only — **never print secrets**)
+
+Do **not** use legacy flat paths (`.endorlabs-context/openapiv2.swagger.json`,
+`.endorlabs-context/user-docs/`). `endorlabs.init(include_openapi=True)` and
+`sync_openapi()` reconcile or remove them when syncing to `platform/`.
+
+Gitignored paths may be missing from workspace search; try targeted reads before
+concluding context is unavailable.
+
+## Research order
+
+1. Wheel: `agent_knowledge_index_path()` / `agent_knowledge_manifest()` (site-packages), or materialized `.endorlabs-context/sdk/` after `init()`.
+2. Local OpenAPI and user docs under `.endorlabs-context/platform/` (when bootstrapped).
+3. Online API spec and docs only as fallback.
+
+Materialize with `endorlabs.init()` when a cwd-relative tree is needed.

endorlabs-0.2.0/.cursor/rules/endor-namespace-scoping.mdc

@@ -0,0 +1,43 @@
+---
+description: Resolve Project first; pass namespace=project.namespace on project-scoped lists.
+alwaysApply: true
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-namespace-scoping.md
+x-endor-source-sha256: fe36b3e092afebd2332980b5803663d10a38070fde802733020da860312186a3
+---
+
+# Namespace scoping
+
+## OSS catalog plane
+
+`Vulnerability`, `Malware`, `QueryVulnerability`, and `QueryMalware` use registry `scope="oss"`.
+List/get and catalog query creates hit `/v1/namespaces/oss/…` regardless of `Client(tenant=…)`.
+
+## Resource-scoped operations
+
+When you have a resource instance (from `list(traverse=True)`), pass the resource object to
+`get`, `update`, or `delete` so namespace is resolved from the resource.
+
+- **List/filter scoped to a resource:** Use **`namespace=resource.namespace`** or
+  `list(parent=resource)` where supported.
+- **Discovery:** Root namespace + `traverse=True` (concurrent namespace fan-out is
+  the SDK default; pass `concurrent=False` to opt out).
+
+## Project-scoped lists (MUST)
+
+`Client(tenant=<client_tenant>)` with default `traverse=False` lists **only that path segment**—not
+child namespaces where projects usually live. A filter such as `spec.project_uuid==…` does **not**
+widen the path.
+
+**Resolve the `Project` row first**, then pass **`namespace=project.namespace`** on downstream lists
+(`Finding`, `ScanResult`, `PackageVersion`, `DependencyMetadata`, …). Otherwise you often get
+**empty results with no error** (the SDK may emit a `UserWarning` on empty tenant-root lists for
+these resources).
+
+**Do not confuse:** `Client(tenant=…)` (auth) with **`--namespace` scope** on bulk workflows (`endor-estate pull -n …`) — namespace scope may be tenant root **or** a child namespace; see [docs/estate/README.md](../../docs/estate/README.md). Do not run bulk pull unless the user explicitly requests it.
+
+Alternatives:
+
+- `Client(tenant=project.namespace)` for the rest of the session, or
+- `traverse=True` only when deliberately searching tenant-wide (higher cost).
+  Pass `concurrent=False` for a single sequential traverse query.

endorlabs-0.2.0/.cursor/rules/endor-portable-examples.mdc

@@ -0,0 +1,45 @@
+---
+description: Use placeholders in git-tracked agent content; never commit customer estate identifiers (tenants, project URLs, production UUIDs).
+globs:
+  - src/endorlabs/**
+  - **/*.py
+  - **/.endorlabs-context/**
+  - agent-knowledge/**
+  - docs/**
+  - devtools/**
+alwaysApply: false
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-portable-examples.md
+x-endor-source-sha256: b45b085c3017366ce44ac2b0a9646a9d4fdc2b27ee7f58d4250d222a7d89b84e
+---
+
+# Portable examples
+
+Git-tracked agent skills, contracts, and generated bundle content must not embed
+**estate identifiers** from customer organizations. There is **no** automated
+substring allowlist—apply judgment using the classes below.
+
+## Name classes
+
+| Class | Meaning | In git-tracked agent content |
+|-------|---------|------------------------------|
+| **Placeholders** | `<tenant>`, `<namespace>`, `<project-uuid>`, `tenant.namespace`, `https://github.com/org/repo.git` | **Required** in commands and snippets |
+| **Product vocabulary** | Platform features, connector types, resource kinds, scan categories in product/user-docs | OK when describing *how the product works* |
+| **Estate identifiers** | Tenant roots, child namespaces, registered project URLs/names, production UUIDs | **Never** commit; resolve from env, user input, or API at runtime |
+
+## Integration surface vs inventory record
+
+A label may name a **platform integration surface** (documented connector or SCM
+capability) or a **tenant-owned inventory record** (a Project UUID or registered
+repository URL). Portable docs use only the former class generically; inventory
+records are session data.
+
+When unsure, prefer a placeholder. Do not add repo-specific "exceptions" for
+particular customer names, tenant paths, or UUIDs—those belong in session context,
+integration tests with env vars, or user-provided inputs.
+
+## Runtime resolution
+
+- Tenant/namespace: `ENDOR_NAMESPACE`, CLI `--tenant` / `--namespace`, or `Client(tenant=…)`.
+- Project: user-provided URL/UUID or `Project.list` / `resolve_project` at runtime.
+- Never hardcode production UUIDs in skills or contracts.

endorlabs-0.2.0/.cursor/rules/endor-workflow-composition.mdc

@@ -0,0 +1,74 @@
+---
+description: Prefer workflow CLI, then library imports, then Client; extend artifacts instead of re-fetching discovery.
+globs:
+  - src/endorlabs/**
+  - **/*.py
+  - **/.endorlabs-context/**
+  - agent-knowledge/**
+  - docs/**
+  - devtools/**
+alwaysApply: false
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-workflow-composition.md
+x-endor-source-sha256: 79c7285a426c54a55605c3868226ac5f0cf085d055ef6b971abefdf0f9f75eb7
+---
+
+# Workflow composition
+
+## Layer boundaries
+
+| Layer | Location | Responsibility | Must not |
+|-------|----------|----------------|----------|
+| **Primitives** | `Client`, `APIClient` | CRUD/list/get per resource | Orchestration, file I/O, argparse |
+| **Tools** | `endorlabs.tools.*` | Reusable domain utilities (e.g. dependency explorer) | Tenant-wide workflow opinions, CLI mains |
+| **Workflow libraries** | `endorlabs.workflows.*` (non-`cli`) | `Client` in → typed `WorkflowResult` out | `print()`, argparse, cwd-relative writes |
+| **Workflow CLIs** | `*.cli`, `troubleshooting_scans/*` | Args, artifacts, filenames | Become copy-paste targets for agents |
+| **Session scripts** | `workspace/sessions/<user>/scripts/` | Thin glue on artifacts + library imports | Live in `src/`, reimplement discovery |
+
+`endorlabs.workflows` ships **documented contracts** — prefer importing
+`library_entrypoints` from `MANIFEST.json` over vendoring workflow source.
+
+## Escalation ladder
+
+Use one step at a time:
+
+1. **Workflow CLI** — run the skill's documented command with defaults.
+2. **Workflow library** — import composable functions (see `MANIFEST.json` `library_entrypoints`).
+3. **`Client` facade** — when no workflow covers the query.
+4. **Session script** — minimal glue under `sessions/<user>/scripts/` (see `endor-workspace-layout`).
+
+## Artifact-first
+
+After a workflow run, treat outputs as source of truth:
+
+- Read `context_manifest.json`, troubleshooting JSON, or step artifacts **before** re-listing the API.
+- Thread `namespace` and UUIDs from artifacts into downstream calls.
+- Do not repeat `Project.list(traverse=True)` when a prior step already wrote project JSON.
+
+## Supported library imports
+
+Generic entrypoints (no estate literals):
+
+- `endorlabs.workflows.projects.resolve.resolve_project`
+- `endorlabs.workflows.common.WorkflowResult`
+- `endorlabs.workflows.policies.run_validate_policy`
+- `endorlabs.workflows.estate.export_version_cardinality_for_package_match`
+- `endorlabs.workflows.callgraph.run_callgraph_sweep`
+- `endorlabs.workflows.troubleshooting_scans` — `list_scan_results_for_project`, `resolve_project`, …
+- `endorlabs.workflows.agent_context.hydration` — per-project BOM/CG hydration primitive; not a workflow orchestrator
+- `endorlabs.tools.dependency_explorer` — backward-compatible re-exports of the hydration/call-graph modules above
+
+See `MANIFEST.json` → `workflows[].library_entrypoints` for the catalog row tied to each skill.
+
+## Anti-patterns
+
+- Run **`endor-estate pull`** (namespace-wide bulk collect) unless the user explicitly requests it — see [docs/estate/README.md](../../docs/estate/README.md).
+- Copy-paste a workflow CLI `main()` into a session script.
+- Unbounded re-fetch to "fix" empty rows (check namespace first).
+- Add triage code under `src/endorlabs/` during an investigation.
+- Fork filename/JSON contracts when extending troubleshooting pipelines.
+
+## When to promote
+
+Reusable, tested orchestration belongs in `endorlabs.workflows` (contributor PR), not a
+permanent session script.

endorlabs-0.2.0/.cursor/rules/endor-workspace-layout.mdc

@@ -0,0 +1,61 @@
+---
+description: Write session/triage artifacts under workspace/sessions/<user>/; not repo-root .tmp/.
+globs:
+  - src/endorlabs/**
+  - **/*.py
+  - **/.endorlabs-context/**
+  - agent-knowledge/**
+  - docs/**
+  - devtools/**
+alwaysApply: false
+x-endor-generated: true
+x-endor-source: agent-knowledge/rules/endor-workspace-layout.md
+x-endor-source-sha256: 18bd45fc8873c9654680a3f18bf343769abfa5f92a4e6b5b017f578d913523fb
+---
+
+# Workspace layout
+
+Run outputs and agent-written files belong under **`.endorlabs-context/workspace/`**
+(gitignored). Do **not** write session/triage debugging artifacts or ad-hoc probe
+scripts to repo-root `.tmp/` unless the user explicitly requests that path.
+
+## Subdirectories
+
+| Subdir | Use for |
+|--------|---------|
+| `<slug>-<YYYYMMDD>/` | Estate pull + analyze (`endor-estate`; `data/`, `intermediate-representation/`, `viz/`) |
+| `projects/<uuid>/` | Project-scoped workflow bundles (`endor-agent-context`, reachability exports, relationship maps) |
+| `sessions/<user>/` | Interactive session, RCA/triage exports, one-off scripts, and other non-project scratch work |
+| `artifacts/` | Namespace-scoped inventory outputs (e.g. **`SemgrepRule`** metadata inventory from `endor-semgrep-inventory`) |
+
+Common session subfolders (create as needed):
+
+- `sessions/<user>/troubleshooting/` — scan RCA (`troubleshooting_scans` workflow default)
+- `sessions/<user>/scripts/` — temporary probe/debug `.py` files for the current investigation
+- `sessions/<user>/exports/` — structured JSON/CSV from auth/SSO/policy spot-checks
+- `sessions/<user>/notes/` — ephemeral markdown (readiness reports, doc audits, design spikes)
+
+## Ephemeral markdown (do not commit)
+
+Short-shelf-life notes belong under **`sessions/<user>/notes/`**, not tracked `docs/`.
+Do not add `docs/findings/`, `*-draft.md`, or `*-assessment.md` under git. Durable
+public docs live in `docs/guides/` (consumers) and `docs/contributing/` (maintainers).
+Breaking changes and notable releases: [docs/changelog.md](../../docs/changelog.md) only — no parallel `*-migration.md`.
+See [docs/design.md](../../docs/design.md) placement rules.
+
+## Resolving `<user>`
+
+Derive a short directory slug from `Client().whoami()` (email local-part, sanitized).
+When identity is unknown, use `agent`.
+
+## Agent rules
+
+1. **Project workflows** — pass `--output-dir .endorlabs-context/workspace/projects/` (or omit when the CLI default is already `workspace/projects`).
+2. **Triage / debugging** — write artifacts under `.endorlabs-context/workspace/sessions/<user>/` (add a task subdir when helpful).
+3. **Temp scripts** — create under `sessions/<user>/scripts/`; never commit them to `src/` or repo root.
+4. **Ephemeral markdown** — readiness assessments, audit logs, and spike notes go under
+   `sessions/<user>/notes/`; do not commit under `docs/`.
+5. **Do not** assume `.endorlabs-context/` exists; `mkdir -p` parent dirs before writing.
+
+Path helpers (SDK): `endorlabs.context.paths.workflow_projects_root`,
+`workflow_sessions_root`, `workflow_artifacts_root`.

endorlabs-0.2.0/.cursorignore

@@ -0,0 +1,17 @@
+# Override .gitignore — let Cursor AI see these gitignored directories.
+# .gitignore keeps them out of version control; ! negations here let Cursor index them.
+
+# API spec + user docs (context bootstrap)
+!.endorlabs-context/
+!.endorlabs-context/**
+!.endorlabs-context/docs/
+!.endorlabs-context/docs/**
+!.endorlabs-context/session-*
+
+# Research files, responses
+!.tmp/
+!.tmp/**
+
+# Generated files
+!.generated/
+!.generated/**

endorlabs-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,30 @@
+# CODEOWNERS — last matching pattern wins.
+# Teams: @endorlabs/<slug>  Users: @username
+
+# Default owner for the SDK repo
+* @endorlabs/engineering
+
+# CI, releases, GitHub automation
+/.github/ @endorlabs/engineering
+
+# IDE agent rules and skill mirrors
+/.cursor/ @endorlabs/engineering
+
+# Maintainer automation and model sync
+/devtools/ @endorlabs/engineering
+
+# Agent knowledge (authoring + shipped wheel copy)
+/agent-knowledge/ @endorlabs/engineering
+/src/endorlabs/agent_knowledge/ @endorlabs/engineering
+
+# Runtime SDK
+/src/ @endorlabs/engineering
+
+# Tests
+/tests/ @endorlabs/engineering
+
+# Documentation (user + contributor guides)
+/docs/ @endorlabs/technical-documentation
+/README.md @endorlabs/technical-documentation
+/CONTRIBUTORS.md @endorlabs/technical-documentation
+/AGENTS.md @endorlabs/engineering

endorlabs-0.2.0/.github/actions/release-build-gate/action.yml

@@ -0,0 +1,68 @@
+name: Release Build Gate
+description: >-
+  Quality gate, ship-artifact verification, and wheel build shared by production
+  and TestPyPI release workflows.
+
+inputs:
+  version:
+    description: PEP 440 version (sets SETUPTOOLS_SCM_PRETEND_VERSION)
+    required: true
+  fetch-spec:
+    description: Download live OpenAPI spec before ship-artifact verify
+    required: false
+    default: "true"
+  verify-changelog:
+    description: Require docs/changelog.md section ## {version}
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - name: Set release version
+      shell: bash
+      run: |
+        echo "SETUPTOOLS_SCM_PRETEND_VERSION=${{ inputs.version }}" >> "$GITHUB_ENV"
+        echo "Release version: ${{ inputs.version }}"
+
+    - name: Verify hatch-vcs version resolution
+      shell: bash
+      run: >-
+        uv run python devtools/check_vcs_version.py
+        --expect "${{ inputs.version }}"
+        --release-only
+
+    - name: Run quality gate
+      shell: bash
+      run: |
+        uv run ruff check .
+        uv run ruff format --check .
+        uv run pyright
+        uv run pytest tests/unit/ -x -m "not interactive and not long"
+
+    - name: Verify ship artifacts
+      shell: bash
+      run: |
+        set -euo pipefail
+        ARGS=(run python devtools/verify_ship_artifacts.py)
+        if [ "${{ inputs.fetch-spec }}" = "true" ]; then
+          ARGS+=(--fetch-spec)
+        fi
+        if [ "${{ inputs.verify-changelog }}" = "true" ]; then
+          ARGS+=(--verify-changelog "${{ inputs.version }}")
+        fi
+        uv "${ARGS[@]}"
+
+    - name: Build package
+      shell: bash
+      run: uv build
+
+    - name: Verify distribution metadata
+      shell: bash
+      run: uv run twine check dist/*
+
+    - name: Smoke test built wheel
+      shell: bash
+      run: >-
+        uv run python devtools/smoke_test_wheel.py
+        --expect-version "${{ inputs.version }}"

endorlabs-0.2.0/.github/actions/setup-python-uv/action.yml

@@ -0,0 +1,34 @@
+name: 'Setup Python with UV'
+description: 'Setup Python and UV with dependency caching for Endor Labs SDK'
+inputs:
+  python-version:
+    description: 'Python version to use'
+    required: true
+    default: '3.13'
+  uv-version:
+    description: 'UV version to install'
+    required: false
+    default: '0.9.3'
+  install-dependencies:
+    description: 'Whether to install dependencies'
+    required: false
+    default: 'true'
+runs:
+  using: 'composite'
+  steps:
+    - name: Install UV
+      uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      with:
+        version: ${{ inputs.uv-version }}
+        python-version: ${{ inputs.python-version }}
+        enable-cache: true
+        cache-dependency-glob: |
+          **/pyproject.toml
+          **/uv.lock
+
+    - name: Install dependencies (dev only)
+      if: inputs.install-dependencies == 'true'
+      shell: bash
+      run: |
+        echo "Installing dependencies..."
+        uv sync --dev

endorlabs-0.2.0/.github/copilot-instructions.md

@@ -0,0 +1,21 @@
+# Endor Labs SDK – Repository instructions for GitHub Copilot
+
+**Project**: Endor Labs SDK for Endor Labs. API-first platform for security governance.
+
+---
+
+## What to seek when suggesting or reviewing code
+
+**Security**: Actively look for security issues. Examples: credential or secret handling (use env only; no hardcoding); injection or unsafe use of user-controlled input in paths or request bodies; missing or weak validation of API responses; dependency or supply-chain concerns. Prefer safe defaults and fail closed where appropriate.
+
+**SDK consumer UX**: View changes from the perspective of someone using this SDK in their application. Prefer clear, consistent naming; predictable error handling (use exception classes exported by `endorlabs`, implemented in `endorlabs.core.exceptions`; no silent swallowing); helpful docstrings and type hints; ergonomic defaults (e.g. `traverse=True` for tenant-wide queries where documented). Avoid breaking or surprising behavior for existing callers; preserve backward compatibility unless explicitly changing the contract.
+
+**Consistency and parity with API spec and docs**: Keep SDK models and resource behavior aligned with the authoritative API definition and user documentation. When adding or changing resources or models, check the OpenAPI spec and user docs for path names, request/response shapes, required vs optional fields, and documented semantics. Flag drift (e.g. SDK fields or behavior that no longer match the spec or docs) and suggest corrections. Use the references below.
+
+---
+
+## Reference – API spec and user docs
+
+- **API spec (OpenAPI)**: <https://api.endorlabs.com/download/openapiv2.swagger.json> (schema drift workflow downloads to `.endorlabs-context/platform/openapi/` in CI; folder is gitignored)
+- **User documentation**: <https://docs.endorlabs.com/> — sitemap <https://docs.endorlabs.com/sitemap.xml>
+- **In-repo docs**: `docs/README.md` (index), `docs/contracts.md` (naming, traverse, ListParameters), `docs/reference/namespace.md`, `docs/contributing/architecture.md`, `docs/contributing/api-validation.md`, `docs/contributing/integration-resource-tests.md`, `docs/contributing/docs-drift-workflow.md`