# AI Agent Project Memory

This file is a durable notebook for AI agents maintaining or enhancing this
repository. Keep it concise, current, and useful enough that the next session
can avoid a full repository rescan.

## How To Use This File

- Add stable knowledge, design decisions, subsystem maps, verification notes,
  and handoff details.
- Prefer summaries with file paths over long pasted command output.
- Delete or update stale notes when later work proves them wrong.
- Keep unrelated work in separate entries.
- Use this file for project memory; use `AGENTS.md` for standing workflow rules.

Recommended read order when resuming work:

1. Handoff Notes
2. Quick Project Map and relevant Subsystem Notes
3. Progress Log
4. Build And Test Facts

## Quick Project Map

| Path | Purpose |
| --- | --- |
| `src/` | Main OpenLiteSpeed server code and built-in modules. |
| `src/http/` | HTTP request, response, header, vhost, listener, and context logic. |
| `src/h2/` | HTTP/2 implementation. |
| `src/quic/` | QUIC / HTTP/3 integration code. |
| `src/modules/` | Optional and built-in modules such as cache, Lua, gzip, pagespeed, and upload progress. |
| `src/extensions/` | Backend/proxy extension integrations: CGI, FastCGI, LSAPI, SCGI, uWSGI, JK, and proxy. |
| `src/lsr/` | Low-level C runtime utilities mirrored by headers in `include/lsr/`. |
| `src/lstl/` | Local C++ utility/container support. |
| `src/lshpack/` | Bundled HPACK implementation and tests. |
| `include/` | Public/shared headers, module API headers, and `lsr/` C API headers. |
| `test/` | Unit tests and server fixture tree. Tests are enabled by Debug CMake builds on Linux. |
| `addon/example/` | Example modules and module API usage samples. |
| `support/` | Support binaries built by the top-level CMake project. |
| `lshostexec/` | Host execution helper built by the top-level CMake project. |
| `doc/` | Maintainer and developer documentation. |

## Build And Test Facts

- The top-level `CMakeLists.txt` declares `Project(openlitespeed VERSION 1.9.0)`.
- Linux `Debug` builds set `ASAN`, `BUILD_TEST`, define `RUN_TEST`, and add the
  `test/` subdirectory.
- The CMake project sets `CMAKE_EXPORT_COMPILE_COMMANDS ON`.
- The build may run `git submodule update --init --recursive --force` unless
  `GIT_SUBMODULE` is disabled.
- `.editorconfig` requires LF endings, final newline, and four-space indentation
  for C/C++, shell, and PHP files.

Useful starting commands:

```bash
git status --short
git log --oneline -8
cmake --build build -j2
```

## Design Notes

Record decisions that should survive across sessions.

| Date | Area | Decision | Rationale | Files |
| --- | --- | --- | --- | --- |
| YYYY-MM-DD | example | Keep this row format. | Makes decisions searchable and easy to review. | `path/to/file` |

## Subsystem Notes

Use this section for facts discovered while working in a subsystem.

### HTTP

- Add notes here after reading or changing `src/http/` or related tests.

### Modules

- Add notes here after changing `src/modules/`, module API headers, or addon
  examples.

### LSR Runtime

- Add notes here after changing `src/lsr/` and `include/lsr/`.

### Tests

- Unit tests use `UnitTest++` style with `SUITE(...)` and `TEST(...)` blocks
  guarded by `RUN_TEST` in many files.

## Progress Log

Use one entry per focused task. Keep entries short and link to files where
possible.

### 2026-04-29 - Add AI Agent Maintainer Docs

- Goal: Add persistent AI-agent guidance so future sessions can avoid repeated
  full-tree rediscovery.
- Files changed: `AGENTS.md`, `doc/AI_AGENT_PROJECT_MEMORY.md`.
- Summary: Added repo-wide working rules, project memory conventions, a quick
  project map, build/test facts, progress and handoff templates, and commit
  hygiene guidance.
- Verification: Reviewed markdown contents and checked `git status --short`.
- Follow-up: Add subsystem-specific facts as future code work discovers them.

### YYYY-MM-DD - Short Task Name

- Goal:
- Files changed:
- Summary:
- Verification:
- Follow-up:

## Handoff Notes

Use this section when stopping with unfinished work or important context.

### 2026-04-29 - AI Docs Initial State

- Current state: Initial AI-agent markdown guidance has been added.
- Next step: For future implementation tasks, read `AGENTS.md`, then this file,
  then inspect only the relevant source and test files.
- Risks or unknowns: No subsystem-specific design facts have been validated
  beyond the top-level layout and build/test facts recorded above.
- Useful commands: `git status --short`, `git log --oneline -8`,
  `cmake --build build -j2`.

### YYYY-MM-DD - Short Handoff Title

- Current state:
- Next step:
- Risks or unknowns:
- Useful commands:

## Commit Planning Notes

Before committing, check that the staged set is one coherent change.

Suggested body fields for non-trivial commits:

```text
What changed:
- ...

Why:
- ...

How:
- ...

Improvement:
- ...

Problem solved:
- ...
```
