MSX2 BASIC Knowledge Base
A source-grounded knowledge base for a future model that reads and generates MSX2 BASIC programs, supported by language documentation, authentic program listings, and validation tools.

GIT gitlab.gif

MSX2 BASIC / Knowledge base
Project archive · Prompt history
The conversation behind the knowledge base

Building knowledge.
One prompt at a time.

A chronological record of the requests that shaped the MSX2 BASIC knowledge base — from its initial structure to validation tools and generation rules.

7User prompts01–07Selected sequenceENEnglish edition
AI responses are not included in the source file.

This selected history contains user requests and accompanying context notes. Entry 001 was backfilled on September 19, 2026; its original receipt time is unavailable. Automatically injected application context is excluded.

7 of 7 prompts

User promptDate not recorded

Initial project structure

Create a structure for storing the MSX2 Basic language model:
language-knowledge/
├── README.md
├── specification/
│   ├── overview.md
│   ├── lexical-rules.md
│   ├── types.md
│   ├── variables.md
│   ├── expressions.md
│   ├── control-flow.md
│   └── runtime.md
│
├── commands/
│   ├── move.md
│   ├── create.md
│   ├── print.md
│   └── wait.md
│
├── grammar/
│   ├── language.ebnf
│   └── tokens.md
│
├── registry/
│   ├── commands.yaml
│   ├── types.yaml
│   └── diagnostics.yaml
│
├── examples/
│   ├── basic/
│   │   ├── hello.xyz
│   │   └── variables.xyz
│   ├── intermediate/
│   └── advanced/
│
├── tests/
│   ├── valid/
│   ├── invalid/
│   └── runtime/
│
└── prompts/
    └── generation-rules.md

External AI contribution

An external AI result was used and added here.

External prompt:

Stage 1. Prepare knowledge about the language. What format should the documentation use? What file types and/or file structures should be used?
User promptOriginal English

Populate the knowledge base

We are going to build language-knowledge base for the future MSX2 Basic Model.
Read the book in the folder @"C:WorkspaceMSX2_LLMMSX2 docs"
Go other language-knowledge and fill in relevant data. 
Remove irrelevant stub files.
File extension for basic files is .bas

Knowledge source

The following book was used to create the knowledge base: MSX2 Technical Handbook.

User prompt

Learn from authentic BASIC examples

Recursively read this path: C:WorkspaceMSX2_LLMMSX2 docsBAS Examples
These are real, correct programs written in MSX2 Basic.
Improve language-knowledge

Example programs

The following BASIC listings were used as examples: File-Hunter BASIC Listings.

User promptOriginal English

PowerShell detokenizer

You had used a two pass detokenizer. Create a powershell script with the detokinizer in tools/detokinizer
User prompt

Level-one syntax checker

### Build a syntax checker

Having a checker will greatly improve the result, but it does not have to be ready before the first prototype.

It is better to divide validation into three levels.

#### Level 1 — a simple validator

Implement:

- maximum line length checks;
- string literal validity checks;
- balanced parentheses checks;
- known command checks;
- command parameter checks;
- reference checks for `GOTO`, `GOSUB`, `THEN`, `RESTORE`;
- `FOR`/`NEXT` matching;
- `IF` compliance with MSX BASIC syntax;
- checks that called subroutines exist;

Place the checker script in tools/syntaxChecker
User prompt

BASIC generation rules in AGENTS

Add to AGENTS:

# MSX2 BASIC generation rules

1. Generate code only for MSX2 BASIC.
2. Do not use GW-BASIC, QuickBASIC, or Visual Basic syntax.
3. Before generation, find the following in language-knowledge:
   - a description of every command used;
   - at least one similar example program.
4. Do not invent commands, functions, or parameters.
5. All GOTO, GOSUB, THEN, and RESTORE jumps must lead
   to existing lines.
6. Check FOR/NEXT and GOSUB/RETURN matching.
7. Take the selected SCREEN mode into account.
8. Return the complete program listing by default.
9. If a required capability is not described in the knowledge base,
   report this instead of inventing syntax.
User prompt

Root knowledge routing index

Add a root index, for example:

language-knowledge/
├── INDEX.md
├── registry/
│   └── commands.yaml
├── commands/
├── specification/
├── examples/
└── grammar/

Describe routing in INDEX.md, for example:

# Knowledge index

## Graphics

- commands/screen.md
- commands/line.md
- commands/circle.md
- examples/graphics/

## Sprites

- commands/sprite.md
- commands/put-sprite.md
- examples/sprites/

## Sound

- commands/sound.md
- commands/play.md
- examples/sound/

## Files

- commands/open.md
- commands/close.md
- commands/input.md
- examples/files/

So that the agent reads INDEX.md first instead of scanning all of language-knowledge.