# BlackLang AI Agent Contract

This document defines how AI coding agents should work with BlackLang today.

It exists to prevent agents from inventing unsupported syntax or presenting a prototype as official BlackLang behavior.

## Official Source Path

Current official BlackLang projects use:

```text
.black source files
.blackthm theme/profile files
black CLI commands
generated web output
```

The official edit loop is:

```bash
black agent startup --json
black docs --all --json
black inspect app.black --json
black format --check --json
black lint --json
black validate --json
black build
```

If a repository includes `blacklang.toml`, use it to find the active source, output directory, target, and theme file.

## Current Capability Boundary

BlackLang v0.2 is strongest for compact, deterministic web application intent:

```text
app
target web
entity
relation fields
page
view order
table
form
actions
auth
roles/access
workflow
state
component variants
validation
computed display fields
custom queries bound to pages
i18n field labels
inline UI intent
OpenAPI output
Docker deployment intent
source security scanning
production packaging
AI-readable docs/inspect/explain output
```

Current BlackLang does not yet provide a general browser runtime or arbitrary frontend event language.

These are not official BlackLang features yet:

```text
<script type="text/black">
browser-side BlackLang interpreter
calculator/game expression runtime
custom button click handlers
arbitrary JavaScript replacement
general-purpose programming
provider-specific integrations without extensions
```

If a task requires one of these, the agent should say that it is outside the current BlackLang capability boundary.

## Do

- Read local project docs before editing.
- Treat `.black` and `.blackthm` files as source of truth.
- Use the official `black` CLI when available.
- Prefer `black docs <keyword> --json` or `black explain <keyword> --json` over guessing syntax.
- Use normal generated or hand-written web code only when the requested behavior is outside current BlackLang support.
- Clearly label prototypes as prototypes when they are not produced by the official compiler.
- Keep secrets out of `.black` files.

## Do Not

- Do not invent new BlackLang syntax and present it as official.
- Do not use `<script type="text/black">` unless an official browser runtime exists.
- Do not claim a feature is generated by BlackLang when it was hand-written.
- Do not manually edit generated output as the normal solution.
- Do not hide current limitations from the user.
- Do not treat BlackLang as a full Python/JavaScript replacement yet.

## Calculator Example Boundary

A simple calculator currently needs:

```text
button click events
local expression state
custom frontend behavior
keyboard handlers
```

Entity-based computed display fields are now supported for generated table/detail UI, but calculator-style local expression state and button event handling still belong to future frontend logic and event phases.

Today, an agent may build a calculator as a normal one-file HTML/JavaScript prototype, but it should not call that prototype official BlackLang output unless it was generated by the official `black` compiler from supported `.black` syntax.

## Correct Agent Response Pattern

When a user asks for something outside current BlackLang support, respond like this:

```text
BlackLang does not support this as official syntax yet.
I can either:
- build a normal web prototype and label it as non-BlackLang output, or
- add the missing BlackLang feature to the compiler first, then generate it.
```

For repository work, prefer the second option when the user is developing BlackLang itself.

## Current Status Claim

Safe current claim:

```text
BlackLang v0.2 can describe and generate useful CRUD/admin-style web applications with auth, roles, relations, workflow, validation, computed display fields, custom queries, i18n labels, inline UI intent, page view order, OpenAPI, Docker deployment, source-security checks, production packaging, and AI-readable CLI outputs.
```

Unsafe current claim:

```text
BlackLang can replace JavaScript, Python, or all browser logic today.
```

Long-term target claim:

```text
BlackLang aims to grow toward a Python-like general-purpose language after the web target matures, while preserving deterministic AI-friendly source design.
```