# BlackLang

BlackLang is an AI-native deterministic intent language for describing application intent in compact `.black` source files.

Current version: 0.1.0-dev
Primary target: web applications
Source extension: `.black`
Theme extension: `.blackthm`

Read first:

- `/` for human-readable documentation.
- `#quick-start` for the smallest complete example.
- `#syntax` for top-level syntax.
- `#entity` for data models.
- `#page` for generated web screens.
- `#table` for list rendering.
- `#form` for data input.
- `#auth` for email/password cookie sessions.
- `#roles` for role and access rules.
- `#theme` for `.blackthm` UI theme/profile files.
- `#ui-profile` for compact positional UI slot rules.
- `#security` for source security rules.
- `#cli` for machine-readable commands.
- `#ai-agents` for `black agent startup --json` project entry output.
- `#errors` for diagnostic JSON shape and code families.
- `/diagnostics.md` for the stable diagnostic code reference.
- `/theme-profile.md` for the stable `.blackthm` format reference.
- `/ui-profile.md` for compact UI slot profile rules.
- `#ai-agents` for agent workflow.
- `#crm-template` for the first reusable SalesCRM template benchmark.
- `#inventory-template` for the InventoryControl template benchmark.
- `#helpdesk-template` for the SupportDesk template benchmark.
- `#invoice-template` for the InvoiceFlow template benchmark.
- `#appointment-template` for the AppointmentBook template benchmark.
- `#project-management-template` for the ProjectPulse template benchmark.

Agent rule:

1. Run `black agent startup --json` when available.
2. Read the returned `readFirst` files that exist.
3. Run `black theme inspect --json` before writing future inline UI intent when a theme file exists.
4. Use returned `profile.rules` and `profile.modes[].slots` as the source of truth for compact UI values.
5. Run `black inspect <file> --affected <symbol> --json` before high-impact source edits.
6. Modify `.black` and `.blackthm` source files, not generated output.
7. Run `black format --check --json`, `black lint --json`, and `black build`.
8. Use `/diagnostics.md`, `docs/diagnostics.md`, or `black docs diagnostics --json` when interpreting diagnostic codes.
9. Keep secrets out of `.black` files. Use `env DATABASE_URL` style references.