# AGENTS.md — AstralView Repo Rules (AI + Human)

This repository is a **high-quality monorepo**. Any change must keep the system:
- **Correct** (tests + typechecks)
- **Understandable** (clean architecture + docs)
- **Low-coupling** (SDK is framework-agnostic)
- **High availability mindset** (resilience, safe defaults)

## Non‑Negotiables

1) **No big-bang rewrites.** Work in small, reviewable steps.
2) **SDK is sacred.** `packages/sdk` must not depend on React/Vue/DOM. Pure TS.
3) **Editor depends on SDK, not vice versa.**
4) **Docs are truthful.** If docs claim something works, it must be tested.
5) **Keep boundaries explicit.** Cross-package imports must be via package entrypoints.

## Quality Gates (must be green)

- `pnpm -r lint`
- `pnpm -r build`
- `pnpm -r typecheck`
- `pnpm -r test` (when tests exist)

## Architecture Conventions

### packages/sdk
- Expose only stable APIs via `src/index.ts`.
- Use clear layers: `core/` (types + pure functions), `runtime/` (optional adapters).
- Prefer **dependency inversion** (interfaces) over direct imports.

### packages/editor
- React + TypeScript.
- UI state (view) separated from business logic (SDK).
- Any persistence/networking should go through SDK interfaces.

### packages/docs
- VitePress.
- Document the public SDK API and editor usage.

## Code Style
- TypeScript strict.
- No `any` unless justified.
- Prefer explicit names over cleverness.

## Commit Discipline
- Conventional commits recommended: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`.
- Each commit should build.

## Security / Safety
- Do not add telemetry.
- Do not check in secrets.
- Avoid unsafe shell commands in scripts.