# BT AI development portal

## Function

 BT official website provides a set of official knowledge interfaces for general coding AI, intelligent IDE and documentation tools that can be read on demand. It completely covers BT language semantics, syntax, standard library, Web development, `bt_app` desktop development, network and devices, extensions and FFI, while avoiding putting the complete knowledge base into the model context every time.

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

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

 This entrance will require the AI to search first, and then read a single function document, a single stable knowledge block, or a module that is really needed. The interface only returns public documents and does not receive user questions, project source code, model configuration, account number, API Key or other private data.

## 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/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. When the search result is `symbol`, use the complete function contract in the response directly, which is Read `markdown_url` when `doc`, read `content_url` when `block`;
 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 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| |
| `block_name` | String | Knowledge block interface is | None | Search results Stable block name in `content_url` | Single knowledge block to read. |
| `path` | String | The exact documentation interface is | None | Search results Documentation path in `markdown_url` | Function or topic to read Markdown. |
| `knowledge_version` | String | The full package interface is | 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 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| |
| `limit` | Int | No | `8` | `1..20`; illegal value falls back to `8`, which is greater than `20`. Press `20` | The maximum number of search results returned. |

### Conditional request header

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `304 Not Modified`. |
| `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 first reading entry

`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-stage 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-stage 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-bit 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 | None | With `{path}` placeholder | Exact function or theme Markdown interface template. |
| `source_sha256` | String | Yes | None | 64-bit lowercase hexadecimal | Normalized summary of a single knowledge 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-bit lowercase hexadecimal | Raw UTF-8 byte digest of the complete offline package. |
| `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-bit 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 | `/md/docs/...` | The exact Markdown address that the AI should read. |
| `html_url` | String | `doc` Yes | None | `/docs/...` | Human readable page. |
| `module_id` | String | `block` Yes | None | Stable module ID | The module to which the knowledge block belongs. |
| `runtimes` | Array[String] | `block` Yes | 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-bit 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-bit 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 header

| Field | Type | Required | Default value | Valid range or optional value | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `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 | The versioned interface outside the search interface is | None | HTTP entity tag | Conditional request value. |
| `Last-Modified` | String | The versioned interface outside the search interface is | None | RFC 7231 HTTP Date | Conditional request value. |
| `X-BT-Knowledge-Version` | String | AI JSON/text interface is | 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-bit 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`.