# Real Time Logic Documentation for AI Agents

> AI-friendly entry points for Barracuda App Server (BAS), Mako Server, Xedge, Xedge32, and related technologies.
> Use `basapi.md` as the source of truth for BAS API syntax, signatures, and behavior.
> Load only the smallest AI skill set that matches the task.

## Documentation And Skill Selector

- BAS AI skill selector (AGENTS.md)  
  https://realtimelogic.com/downloads/ai-skills/AGENTS.md

- BAS documentation bundle (basapi.md)  
  https://realtimelogic.com/downloads/basapi.md

- ESP32 and Xedge32 API reference (esp32api.md)  
  https://realtimelogic.com/downloads/esp32api.md

- OPC UA API reference (opcuaapi.md)  
  https://realtimelogic.com/downloads/opcuaapi.md

## Reference Priority

1. `basapi.md` - BAS API syntax, function signatures, and runtime behavior.
2. `esp32api.md` - Xedge32 and ESP32-specific APIs and integration patterns.
3. `opcuaapi.md` - OPC UA-specific APIs and integration patterns.
4. If a skill or example conflicts with the relevant API reference, trust the API reference and update the local guidance.

## Optional AI Skill References

Use these skills only when the task touches the matching area. Do not load every skill by default.

- BAS VFS composition, routing, resource readers, directory callbacks, WebDAV, and WFS  
  https://realtimelogic.com/downloads/ai-skills/VFS-skill.md

- Authentication, authorization, sessions, roles, protected paths, and user databases  
  https://realtimelogic.com/downloads/ai-skills/Authentication-Authorization-Skill.md

- General OWASP-style security review for BAS applications and exposed protocols  
  https://realtimelogic.com/downloads/ai-skills/OWASP-General-Security-Skill.md

- LSP browser architecture using server rendering, htmx, Fetch/JSON, WebSocket RPC, or SMQ  
  https://realtimelogic.com/downloads/ai-skills/Build-LSP-Web-Interfaces-Skill.md

- SMQ architecture, topics, browser/device flows, request/reply, presence, and broker authorization  
  https://realtimelogic.com/downloads/ai-skills/SMQ-Skill.md

- SQLite write serialization and the dedicated-writer pattern  
  https://realtimelogic.com/downloads/ai-skills/SQLite-Skill.md

- C/C++ Lua bindings for the BAS Lua environment  
  https://realtimelogic.com/downloads/ai-skills/Lua-Binding-Skill.md

- Mako Server service deployment, fixed paths, unattended operation, logging, rollback, and ACME  
  https://realtimelogic.com/downloads/ai-skills/Deploy-Mako-Server-Skill.md

- Mako Server download, source/binary build, installation artifacts, and build smoke testing  
  https://realtimelogic.com/downloads/ai-skills/MakoBuildSkill.md

- Mako build-skill maintenance and smoke-test alignment  
  https://realtimelogic.com/downloads/ai-skills/UpdatingMakoBuildSkill.md

- Barracuda/BAS/BWS TCP/IP and RTOS porting  
  https://realtimelogic.com/downloads/ai-skills/PortingBarracuda-SKILL.md

## Skill Selection

- Start with VFS when deciding where URLs, files, callbacks, or protected subtrees belong.
- Add authentication for identity, sessions, roles, or protected resources.
- Add OWASP security for untrusted input, public exposure, production readiness, TLS, secrets, uploads, or review.
- Use LSP web interfaces when choosing the browser/server interaction model.
- Use SQLite before designing any request path that writes to SQLite.
- Use SMQ for publish/subscribe, browser/device messaging, presence, discovery, or synchronized clients.
- Use Lua bindings only for native C/C++ integration.
- Use Mako build guidance for producing or aligning Mako binaries and build artifacts.
- Use Mako deployment guidance for unattended service operation, runtime paths, logs, health checks, restart behavior, and certificate lifecycle.
- Use the porting skill for TCP/IP stack, RTOS, and platform adaptation.

Common combinations:

| Task | Skills |
| --- | --- |
| Protected REST or admin subtree | VFS + authentication + OWASP |
| Database-backed browser form/API | LSP web interfaces + SQLite + OWASP |
| Live browser/device dashboard | LSP web interfaces + SMQ; add authentication/OWASP when exposed |
| Production Mako service | Mako deployment; add authentication/OWASP for remotely reachable management |
| Build and deploy a custom Mako binary | Mako build + Mako deployment |
| Native sensor or protocol API | Lua bindings + the relevant runtime API; add VFS or SMQ only for its exposed interface |

## BAS Application Model

- Put startup state, persistent clients, timers, shared helpers, and other application-lifetime resources in `.preload` or modules loaded by `.preload`.
- Provide `onunload()` for sockets, timers, threads, database connections, mounts, hardware handles, and other resources requiring deterministic cleanup.
- In Xedge, use `.xlua` for independent background programs and LSP for browser-facing request/response work. Check `esp32api.md` for Xedge32-specific behavior.
- Xedge `.xlua` environments inherit from `.preload`. LSP pages access shared application state through `app`; they do not inherit `.preload` values as ordinary globals.
- Use request-local state for one request, `page` for per-LSP-resource state shared by all users, `app` for shared application state, and a session for per-user state.
- Treat `_G` as process-global state that may cross applications, pages, requests, and sessions. Do not use it for ordinary application or user state.

## Architecture And Safety

- Keep server-side Lua/LSP responsible for data, device/runtime logic, authorization, validation, and HTTP/SMQ endpoints.
- Keep browser JavaScript responsible for rendering and interaction. Never put server secrets in browser code.
- Define each HTTP or message contract before implementation: method/topic, inputs, validation, response/payload, errors, authorization, timeouts, and retry/idempotency behavior.
- Validate all external input on the server.
- Keep request handlers bounded; move background and application-lifetime work to the runtime mechanism designed for it.
- Keep `.preload`, modules, databases, keys, and configuration out of public URL space.
- Prefer BAS-native APIs and existing application conventions over generic framework assumptions.

## Verification Baseline

- Restart or reload after `.preload` changes and inspect startup/unload behavior.
- After `.xlua` changes, verify activation, trace output, program replacement, and cleanup.
- For LSP/HTTP, verify method, status, content type, response body, validation failures, authorization failures, and side effects.
- For browser UI, test initial load, direct navigation, updates, console errors, and at least one failure path.
- For WebSocket or SMQ, use the intended client handshake and message flow; a plain HTTP request is not a valid protocol test.
- For shared real-time state, use at least two clients and test disconnect/reconnect.
- For deployment, verify foreground startup before service identity, paths, listeners, logs, stop/start, restart policy, and boot startup.

Inspect runtime trace/log output after actions expected to execute Lua. A successful file write or start command does not prove that the application ran correctly.