# BT AI development guide

## Function

The BT website provides public knowledge endpoints for coding assistants, IDEs, and documentation tools. They cover language semantics, syntax, the standard library, Web and desktop development, networking, devices, extensions, and FFI. Clients can retrieve only the material needed for a task.

When providing a separate URL to the AI, use the following:

```text
https://btlang.org/ai
```

The guide instructs clients to search first, then read the relevant function contract, document, stable knowledge block, or module. These endpoints return public documentation only; they do not accept user questions, project source, model configuration, accounts, API keys, or private data.

## Language and canonical URLs

The AI guide, reference modules, function contracts, search results, and current offline bundle use English as their authoritative language. Chinese category keywords remain available as search aliases. Assistants should respond in the user's requested language and follow the target project's code conventions.

Human documentation remains available in English and Simplified Chinese. All localized website URLs put the language first: `/en/docs/{path}`, `/zh-hans/docs/{path}`, `/en/md/docs/{path}`, and `/zh-hans/md/docs/{path}`. AI search links always select English explicitly, independently of browser language or cookies. `/ai` and `/llms.txt` remain global English machine entry points.

Legacy `/md/docs/en/{path}` redirects permanently to `/en/md/docs/{path}`. `/md/docs/zh-hans/{path}` and the historically Chinese `/md/docs/{path}` redirect to `/zh-hans/md/docs/{path}`. The `zh-cn` alias and language-tag casing normalize to lowercase `zh-hans` or `en`. Missing document paths default to `index`; missing documents and unsafe paths return `404`.

## Syntax

```text
GET https://btlang.org/ai
GET https://btlang.org/llms.txt  # Automatically discover compatible aliases, the text is the same as /ai
GET https://btlang.org/ai/manifest
GET https://btlang.org/ai/search?q={query}&limit={limit}
GET https://btlang.org/ai/index
GET https://btlang.org/ai/block/{module_id}/{block_name}
GET https://btlang.org/ai/knowledge/{module_id}
GET https://btlang.org/en/md/docs/{path}
GET https://btlang.org/ai/bundle/{knowledge_version}
```

Recommended reading order:

1. Read only `/ai` for the first time;
2. Use `/ai/search` to query the API name, module name or runtime name;
3. Use a `symbol` contract directly. For a `doc` result, read `markdown_url`; for a `block` result, read `content_url`.
4. Read the entire module only when the system design or semantics are uncertain;
5. The complete index and offline package are only for client caching, offline development or knowledge tool integration.

## Parameters

### Path Parameters

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `module_id` | String | For modules and blocks | None | A stable ID in `modules[].id` | Knowledge module to read. |
| `block_name` | String | For blocks | None | Search results Stable block name in `content_url` | Single knowledge block to read. |
| `path` | String | For documents | None | Search results Documentation path in `markdown_url` | Function or topic to read Markdown. |
| `knowledge_version` | String | For bundles | None | `knowledge_version` | The immutable offline package version of the manifest to download. |

### Query Parameters

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `q` | String | For search | None | 1 to 100 characters; space-separated API, module, or runtime keywords | Every non-empty term must match the same indexed entry. |
| `limit` | Int | No | `8` | `1..20`; invalid or non-positive values use `8`; values above `20` are capped at `20` | The maximum number of search results returned. |

### Conditional request header

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `If-None-Match` | String | No | None | A previous `ETag`; weak tags and comma-separated lists are supported | Returns `304 Not Modified` when the manifest, index, block, module, or bundle is unchanged. |
| `If-Modified-Since` | String | No | None | Last responded `Last-Modified` | `304 Not Modified` is returned when `If-None-Match` is not sent at the same time and the release time is consistent. |

## Return Value

### AI guide

`GET /ai` returns a condensed plain text with Markdown structure as `text/plain; charset=utf-8` to avoid rejection of response by AI crawling components that only accept common web page text types. The main text includes:

- the most token-saving forced reading strategy;
- search, precise documentation, knowledge blocks, modules and offline package addresses;
- module routing, dependency and token estimation;
- shorthand for running, building and accepting BT and `bt-app`.

It is not a full document, and AI should not guess specific function signatures based only on the entry summary.

### Knowledge Manifest

`GET /ai/manifest` Returns UTF-8 JSON:

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `schema_version` | Int | Yes | None | Currently `1` | Manifest structure version. |
| `bt_version` | String | Yes | None | Three-component version | BT version corresponding to knowledge. |
| `knowledge_version` | String | Yes | None | `YYYY.MM.DD.revision` | The only version released by this official knowledge. |
| `updated_at` | String | Yes | None | ISO 8601 | Knowledge release time. |
| `last_modified` | String | Yes | None | RFC 7231 HTTP Date | The last modified time used by the conditional request. |
| `min_client_version` | String | Yes | None | Three-component version | The minimum tool version that can read the current schema. |
| `guide_url` | String | Yes | `/ai` | Absolute path within the site | The only standardized entrance for universal AI. |
| `text_content_type` | String | Yes | `text/plain; charset=utf-8` | Fixed value | Compatible response type used by AI portals, precise documentation, knowledge blocks, and modules; the body still uses Markdown structure. |
| `search_url_template` | String | Yes | None | With `{query}` and `{limit}` placeholders | Small results search interface template. |
| `search_index_url` | String | Yes | `/ai/index` | Absolute path within the site | Complete search index address. |
| `search_index_sha256` | String | Yes | None | 64-character lowercase hex | Full search index raw UTF-8 byte digest. |
| `block_url_template` | String | Yes | None | With `{module_id}` and `{block_name}` placeholders | A single knowledge block interface template. |
| `docs_url_template` | String | Yes | `/en/md/docs/{path}` | With `{path}` placeholder | Canonical English Markdown documentation URL template. |
| `source_sha256` | String | Yes | None | 64-character lowercase hexadecimal | SHA-256 of the normalized English reference source. |
| `bundle_format` | String | Yes | `bt-ai-bundle-json-v1` | Fixed value | Complete offline package format. |
| `bundle_url` | String | Yes | None | `/ai/bundle/{knowledge_version}` | The current complete offline package address. |
| `bundle_sha256` | String | Yes | None | 64-character lowercase hexadecimal | SHA-256 of the exact UTF-8 bytes of the offline bundle. |
| `modules` | Array[Object] | Yes | None | Fixed module list | Knowledge module metadata that can be read on demand. |

`modules[]` Field:

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `id` | String | Yes | None | Stable module ID | Unique identification of the module. |
| `revision` | Int | Yes | None | Greater than or equal to `1` | Module text revision number. |
| `content_url` | String | Yes | None | `/ai/knowledge/{id}` | Markdown address of the entire module. |
| `sha256` | String | Yes | None | 64-character lowercase hexadecimal | The raw UTF-8 byte digest of the module. |
| `approx_tokens` | Int | Yes | None | Greater than `0` | The approximate number of Tokens of the module. |
| `runtimes` | Array[String] | Yes | None | `cli/web/desktop/extension/ffi` | Module applicable runtime. |
| `tags` | Array[String] | Yes | None | Stable search tag | Module topic tag. |
| `depends_on` | Array[String] | Yes | `[]` | Other module ID | Dependencies that should be considered before reading the entire module. |
| `block_count` | Int | Yes | None | Greater than `0` | The number of stable knowledge blocks contained in the module. |

### Search for

`GET /ai/search` by keyword Return small UTF-8 JSON:

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `query` | String | Yes | None | Query text normalized to lowercase | This actual query. |
| `limit` | Int | Yes | `8` | `1..20` | The upper limit of this result. |
| `count` | Int | Yes | None | `0..limit` | Actual returned quantity. |
| `results` | Array[Object] | Yes | `[]` | Function contract, document, or knowledge block result | Exact symbols and exact paths take precedence, followed by related candidates. |

`results[]` Common fields and branch fields:

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `kind` | String | Yes | None | |
| `id` | String | Yes | None | Stable ID | Result identification. |
| `title` | String | Yes | None | Non-empty text | Result title. |
| `approx_tokens` | Int | Yes | None | Greater than `0` | Read the approximate number of Tokens for this result. |
| `signature` | String | `symbol` Yes | None | Markdown inline code | Function calling method. |
| `parameters` | String | `symbol` Yes | None | Text | Parameter name, type and required rules. |
| `defaults` | String | `symbol` Yes | None | Text | Parameter default value. |
| `returns` | String | `symbol` Yes | None | Text | Return type and semantics. |
| `example` | String | `symbol` Yes | None | Markdown inline code | Minimal call example. |
| `notes` | String | `symbol` Yes | None | Text | Behavior boundaries and precautions. |
| `limits` | String | `symbol` Yes | None | Text | Context, permissions, or resource restrictions. |
| `category` | String | `doc` Yes | None | Document Category | The exact category to which the document belongs. |
| `markdown_url` | String | `doc` Yes | None | `/en/md/docs/...` | The exact Markdown address that the AI should read. |
| `html_url` | String | `doc` Yes | None | `/en/docs/...` | Human readable page. |
| `module_id` | String | For `symbol` and `block` | None | Stable module ID | The module to which the knowledge block belongs. |
| `runtimes` | Array[String] | For `symbol` and `block` | None | Runtime list | Knowledge block applicable runtime. |
| `tags` | Array[String] | `block` Yes | None | Tag list | Knowledge block topic tags. |
| `content_url` | String | `block` Yes | None | `/ai/block/...` | The address of the single block of Markdown that the AI should read. |
| `sha256` | String | `block` Yes | None | 64-character lowercase hexadecimal | Single block text summary. |

### Full Search Index

`GET /ai/index` Returns a JSON index of all accurate documents and stable knowledge chunks. It is suitable for IDE or local tools to build caches, but is not suitable for direct use as a model context for ordinary coding tasks.

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `schema_version` | Int | Yes | None | Currently `1` | Index structure version. |
| `knowledge_version` | String | Yes | None | Current knowledge version | Release version to which the index belongs. |
| `source_sha256` | String | Yes | None | 64-character lowercase hexadecimal | Summary of the knowledge source corresponding to the index. |
| `entries` | Array[Object] | Yes | None | `symbol/doc/block` Mixed List | All searchable entries; internally `search_text` and `exact_queries` are search matches only. |

### Single knowledge block and the entire module

`GET /ai/block/{module_id}/{block_name}` returns only a stable Markdown knowledge block; `GET /ai/knowledge/{module_id}` returns the entire module. Both transfer Markdown body as `text/plain; charset=utf-8` and provide SHA-256 and conditional caching response headers.

Knowledge chunks are usually much smaller than the entire module. For example, when you only need the `String` method summary, you should read the corresponding knowledge block; when you only need the precise signature of `string.replace`, you should directly use the `symbol` function contract in the search results.

### Complete offline package

`GET /ai/bundle/{knowledge_version}` Returns `bt-ai-bundle-json-v1` JSON:

| Fields | Type | Required | Default | Valid range or optional | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `schema_version` | Int | Yes | None | Currently `1` | Full package structure version. |
| `bundle_format` | String | Yes | None | `bt-ai-bundle-json-v1` | Complete package format. |
| `knowledge_version` | String | Yes | None | Consistent with the requested version | Knowledge version in the package. |
| `manifest` | Object | Yes | None | Manifest Snapshot | To avoid self-referential hashes, `bundle_sha256` is fixed to `null` within the package. |
| `block_index` | Object | Yes | None | schema 1 | Line number, label, token estimate and summary of all stable knowledge blocks. |
| `modules` | Object[String,String] | Yes | None | Key is module ID | All modules Markdown text. |

### Response headers

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `Content-Language` | String | AI guide, errors, search, versioned knowledge, and raw documents | None | `en` for AI knowledge; `en` or `zh-hans` for raw documents | Response language; explicit URLs are independent of browser preferences. |
| `Content-Location` | String | AI guide and raw documents | None | Absolute canonical HTTPS URL | Canonical location of the returned text. |
| `Content-Type` | String | Yes | None | JSON uses `application/json`; AI text uses `text/plain; charset=utf-8` | Response body format; plain text body remains Markdown Titles, tables and code blocks. |
| `Cache-Control` | String | Yes | None | First read entry 60 seconds; search/knowledge 5 minutes; version package one year and immutable | Client cache strategy; first read entry shortens the cache, so that compatibility adjustments such as content types can take effect quickly. |
| `ETag` | String | For manifest, index, blocks, modules, and bundles | None | HTTP entity tag | Conditional request value. |
| `Last-Modified` | String | For manifest, index, blocks, modules, and bundles | None | RFC 7231 HTTP Date | Conditional request value. |
| `X-BT-Knowledge-Version` | String | For manifest, index, search, blocks, modules, and bundles | None | Current knowledge version | The knowledge version to which the response belongs. |
| `X-Content-SHA256` | String | Indexes, knowledge chunks, modules, and complete packages are | None | 64-character lowercase hexadecimal | A summary of the current response body. |
| `Access-Control-Allow-Origin` | String | The AI interface is | `*` | Fixed to `*` | Allow public knowledge clients to read across domains. |

## Code Examples

 The following BT script searches for `string.replace`, reading the minimal function contract directly:

```bt
search_response = reqwest('https://btlang.org/ai/search')
    .query({q: 'string replace', limit: 5})
    .send()
search_result = search_response.body.parse_json()
symbol = search_result.results.find(fn(item) {
    item.kind == 'symbol'
})

// Output: `string.replace(pattern, replacement)`
print symbol.signature
```

 The following BT script verifies a single knowledge block by manifest:

```bt
block_response = reqwest('https://btlang.org/ai/block/stdlib-core/section-5-2').send()
verified = crypto(block_response.body).sha256() === block_response.headers['x-content-sha256']

// Output: true
print verified
```

## Notes

- Normal coding tasks do not read the full search index, the full module set, or the offline package; search first and read by minimal results.
- `/llms.txt` is an automatically discovered alias agreed by AI tools, and the text format is still Markdown; only `https://btlang.org/ai` is used when developers actively provide links.
- AI portals, precise documentation, knowledge blocks and modules intentionally use the more compatible `text/plain` and do not change back to `text/markdown` which may be rejected by some web page reading components.
- When the API name is known, search for `category api_name` or the complete symbol first, such as `string replace`, `mysql begin`, `window.bt.call`.
- The same development task should always use one `knowledge_version`, and do not mix two versions in the middle of the task.
- Modules, knowledge blocks, indexes or offline packages should be SHA-256 verified against the original UTF-8 bytes after downloading before being written to the official cache.
- The `304` response has no body, the client should continue to use the local verified content.
- When the official website is inaccessible, the tool can fall back to its own built-in and verified complete package; ordinary projects must not assume the existence of fixed local directories such as `E:\bt-lang`.
- The project's own `AGENTS.md`, README, runtime file locations and test commands take precedence over this site's general recommendations.
- Unknown paths, modules or knowledge blocks return `404`, missing search terms return `400`, non-`GET` requests return `405`.