Initial open-source release

AGENTS.md

@@ -0,0 +1,251 @@
+# KTX Development Notes
+
+KTX is a standalone open-source context layer for database agents. These
+instructions apply to all agents working in this repository (Codex, Claude,
+Gemini, and similar tools). Do not assume an external app server, frontend,
+database migrations, ORPC contracts, or `python-service/` layout exist here.
+
+## Critical Rules
+
+### Absolute Requirements
+
+- **MUST**: Use the active agent's task tracker for tasks with 3+ steps or
+  complex operations (`TodoWrite` in Claude, `update_plan` in Codex).
+- **MUST**: Read files before editing them.
+- **MUST**: Complete all tracked tasks before finishing.
+- **MUST**: Activate `.venv` before running Python code when a local virtualenv
+  exists. If no `.venv` exists, use `uv run ...` from the relevant project root.
+- **MUST**: After modifying Python files, run the relevant Python tests and run
+  `uv run pre-commit run --files [FILES]` when a pre-commit config exists. If
+  pre-commit cannot run because config or tool versions are missing, state that
+  explicitly and run the closest available checks.
+- **MUST**: Remove dead code; do not leave commented-out code, unused wrappers,
+  or empty directories.
+- **MUST**: Keep package/public API changes intentional. Do not add compatibility
+  wrappers for old KLO names unless the user explicitly asks for a migration
+  bridge.
+
+### Absolute Prohibitions
+
+- **MUST NOT**: Use raw `pip`; use `uv`.
+- **MUST NOT**: Use `npm` or `bun`; use `pnpm`.
+- **MUST NOT**: Run destructive git cleanup commands (`git clean`,
+  `git reset --hard`, `git checkout .`) unless the user explicitly requested
+  that exact operation.
+- **MUST NOT**: Run `git stash`, `git stash pop`, `git stash apply`, or
+  `git stash drop` without explicit user instruction. Prefer a branch plus
+  commit when the user asks to save work in progress.
+- **MUST NOT**: Reintroduce external app conventions such as ORPC contracts,
+  NestJS controllers, frontend routes, `routeTree.gen.ts`, or app database
+  migration commands unless those systems are intentionally added to KTX later.
+
+### Language Convention
+
+- **MUST**: Absolute requirement, never deviate.
+- **MUST NOT**: Absolute prohibition.
+- **SHOULD**: Strong recommendation, deviate only with good reason.
+- **MAY**: Optional, at agent's discretion.
+
+## Priority Hierarchy
+
+When rules conflict, follow this order:
+
+1. Safety and user intent
+2. Correctness: code works and verification passes
+3. Single source of truth and DRY design
+4. Code quality: types, readable boundaries, focused modules
+5. Performance where it matters
+
+## Repository Shape
+
+KTX is a pnpm + uv workspace.
+
+- TypeScript packages: `packages/*`
+- CLI package: `packages/cli`
+- Core context package: `packages/context`
+- LLM package: `packages/llm`
+- Database connectors: `packages/connector-*`
+- Python semantic layer: `python/klo-sl`
+- Python daemon: `python/klo-daemon`
+- Examples and fixtures: `examples/`
+- Workspace scripts: `scripts/`
+- Local agent skills are private overlays. Do not commit `.agents/` or
+  `.claude/` to this public repository.
+
+Some package names still contain `klo` during the split. Do not mass-rename
+symbols, package names, paths, or docs to `ktx` unless the task asks for that
+rename.
+
+## Quick Commands
+
+### TypeScript Workspace
+
+```bash
+pnpm install
+pnpm run build
+pnpm run type-check
+pnpm run test
+pnpm run check
+pnpm --filter @klo/cli run smoke
+pnpm --filter './packages/*' run build
+pnpm --filter './packages/*' run test
+pnpm --filter './packages/*' run type-check
+```
+
+### Python Workspace
+
+```bash
+uv sync --all-groups
+uv run pytest -q
+uv run pytest python/klo-sl/tests -q
+uv run pytest python/klo-daemon/tests -q
+uv run pre-commit run --files [FILES]
+```
+
+If `pyproject.toml` pins a newer `uv` than the local binary, do not edit the
+pin just to make checks pass. Report the version mismatch and run checks that
+do not require changing project configuration.
+
+### CLI and Release Checks
+
+```bash
+pnpm run setup:dev
+pnpm run link:dev
+pnpm run artifacts:verify
+pnpm run release:readiness
+pnpm run release:published-smoke
+```
+
+## Verification After Changes
+
+Choose the smallest checks that cover the changed surface, then broaden when
+shared contracts or package exports are affected.
+
+- TypeScript package code: `pnpm --filter <package> run type-check` and
+  `pnpm --filter <package> run test`
+- Cross-package TypeScript changes: `pnpm run type-check` and `pnpm run test`
+- Build/export changes: `pnpm run build`
+- Workspace scripts: `node --test scripts/*.test.mjs` or the specific script
+  test file
+- Python semantic layer: `uv run pytest python/klo-sl/tests -q`
+- Python daemon: `uv run pytest python/klo-daemon/tests -q`
+- Python files: also run `uv run pre-commit run --files [FILES]` when
+  pre-commit is configured
+
+For test suites that take a while, capture full output once and inspect that
+file instead of rerunning to apply different filters:
+
+```bash
+pnpm run test 2>&1 | tee /tmp/ktx-test-output.log
+```
+
+## TypeScript Standards
+
+- Use Node 22+ and pnpm workspace commands.
+- Keep packages ESM (`"type": "module"`) and preserve `NodeNext` TypeScript
+  semantics.
+- Prefer strict types over `any`; do not use `as unknown as`.
+- Keep package exports, `types`, and built `dist` expectations aligned when
+  changing public APIs.
+- Use `zod` schemas for runtime validation at CLI/config/API boundaries.
+- Keep connector packages thin: connector-specific scanning/auth behavior
+  belongs in `packages/connector-*`; shared types and orchestration belong in
+  `packages/context`.
+- Avoid circular package dependencies. Shared code should move to the lowest
+  sensible package, not be duplicated across connectors.
+- Do not manually edit generated or built output under `dist/`; edit source and
+  rebuild.
+
+### Zod Naming Convention
+
+```typescript
+const userSchema = z.object({
+  id: z.uuid(),
+  email: z.string().email(),
+  name: z.string(),
+});
+
+type User = z.infer<typeof userSchema>;
+```
+
+Runtime schemas use `camelCase` plus the `Schema` suffix. Static inferred types
+use `PascalCase` without the suffix.
+
+## Python Standards
+
+- Use `pyproject.toml`; do not add `requirements.txt`.
+- Use type hints for new and changed Python code.
+- Use `pathlib` instead of `os.path`.
+- Use `logger.exception()` when catching and logging exceptions.
+- Prefer explicit exception types over broad `except Exception`.
+- Keep `python/klo-sl` focused on semantic-layer planning and SQL generation.
+- Keep `python/klo-daemon` focused on portable daemon/API behavior around the
+  semantic layer.
+
+### SQL and Structured Parsing
+
+- Prefer AST-based parsing over regex for structured input.
+- For SQL, use `sqlglot`; it is already a dependency.
+- In `python/klo-sl`, follow the local `python/klo-sl/AGENTS.md` guidance:
+  parse expressions with sqlglot, quote reserved identifiers before parsing,
+  and generate postgres-shaped SQL before final dialect transpilation.
+- Regex may be used for non-structural sanitization, but not to interpret SQL
+  structure.
+
+## Documentation and Specs
+
+- Keep public documentation in `README.md`, package READMEs, and example
+  READMEs unless the repository intentionally adds a public docs tree.
+- Prefer concrete commands, file paths, and acceptance criteria over broad
+  prose.
+- When documenting examples, ensure referenced files and commands exist in the
+  standalone KTX tree.
+- Remove or rewrite stale external app references unless the doc is explicitly
+  historical.
+
+## LLM and Prompt Development
+
+When creating or modifying agent prompts, system prompts, tool descriptions, or
+skills:
+
+- Use XML tags for major structure when it helps model reliability:
+  `<role>`, `<workflow>`, `<examples>`, `<success_criteria>`.
+- Use positive framing: tell the model what to do.
+- Keep prompts compact and avoid duplicating the same rule in multiple places.
+- Include 1-3 concrete examples when examples materially reduce ambiguity.
+- Use AI SDK v6 patterns for TypeScript LLM work.
+- Use the local `ai-sdk` skill when working with AI SDK code.
+
+## Context7 and External Docs
+
+- Use Context7 when official, current library documentation would materially
+  reduce risk.
+- Context7 "Monthly quota exceeded" errors are often transient. Retry before
+  assuming the quota is exhausted.
+- If Context7 remains unavailable, state the blocked lookup and use the best
+  available local/source documentation.
+
+## When to Ask vs Act
+
+Act without asking when:
+
+- Following explicit user instructions
+- Running verification
+- Fixing clear bugs or tool failures within the requested scope
+
+Ask first when:
+
+- Requirements are ambiguous
+- The next step is destructive or would discard user work
+- A breaking public API decision is not already implied by the task
+- Missing credentials, live services, or external accounts are required
+
+## Git and Worktree Safety
+
+- The worktree may contain unrelated user changes. Do not revert files you did
+  not change unless explicitly asked.
+- Before committing, inspect `git status --short` and commit only intended
+  files.
+- Do not commit ignored dependency/build artifacts such as `node_modules/`,
+  `.venv/`, `dist/`, coverage output, or local databases unless the task
+  explicitly concerns packaged artifacts.