In `@docs/plans/token-usage-tracking.md`:
- Around line 12-36: Fix markdownlint errors by ensuring all fenced code blocks
are surrounded by blank lines and include language tags (e.g., ```go for the
Usage struct block), replace emphasis-used headings (like **1. Core Usage Struct
is Minimal**) with proper heading syntax (e.g., "### Core Usage Struct is
Minimal") and ensure a blank line before/after headings, and run through the
document to correct other lint rules (MD031, MD036, MD040, MD022) so headings
and code blocks follow consistent spacing and language-tag conventions; update
the examples mentioning Usage, StreamLogWrapper and audit log generation to use
proper fenced code blocks and heading markup.

In `@internal/core/errors.go`:
- Around line 158-162: The 404 branch creating NewNotFoundError(message)
currently drops the originalErr; update the case handling so after creating err
:= NewNotFoundError(message) and setting err.Provider = provider you also set
err.OriginalErr = originalErr (matching other branches) before returning to
preserve debugging context; reference NewNotFoundError, err.Provider and
originalErr in your change.

In `@internal/core/responses.go`:
- Around line 73-78: The ResponsesUsage struct currently exposes RawUsage as
map[string]any which weakens payload typing; update ResponsesUsage to replace
RawUsage with json.RawMessage (importing encoding/json) or a dedicated typed
struct to preserve strong typing for provider-specific data, and adjust any
marshaling/unmarshaling code that reads/writes ResponsesUsage (references:
ResponsesUsage, RawUsage) to handle json.RawMessage (or the new typed struct)
instead of a map while keeping the json tag `json:"raw_usage,omitempty"`.

In `@internal/providers/anthropic/anthropic.go`:
- Around line 405-426: Provider.ListModels currently fetches only the first page
(limit=1000) and ignores anthropicModelsResponse.HasMore/LastID; change
ListModels to loop calling p.client.Do repeatedly while anthropicResp.HasMore is
true, passing after_id=anthropicResp.LastID (and limit=1000) on subsequent
requests, appending each page's models (convert with parseCreatedAt into
core.Model) into the same slice, and only return the full core.ModelsResponse
after no more pages remain; use the anthropicModelsResponse struct fields
HasMore and LastID to control pagination and aggregation.
- Around line 434-441: Change parseCreatedAt to log parse errors via the slog
package and return 0 instead of time.Now().Unix() so invalid timestamps are not
silently mapped to current time; specifically, in function
parseCreatedAt(createdAt string) int64 call slog.Error (or slog.With(...).Error)
with a clear message including the invalid createdAt and the parse error, then
return int64(0) on error. Also update the TestParseCreatedAt_InvalidFormat unit
test to expect 0 for invalid/ unparsable timestamps.

In `@internal/server/handlers.go`:
- Around line 55-56: The request ID is being read from the response headers
(using c.Response().Header().Get("X-Request-ID")) which is incorrect; change all
occurrences to read from the incoming request headers (use
c.Request().Header.Get("X-Request-ID")) so the value set by the audit log
middleware is returned—update the occurrences around the requestID variable in
handlers.go (and the similar spots referenced at the other two occurrences) to
use c.Request().Header.Get instead of c.Response().Header().Get.

In `@internal/usage/cleanup.go`:
- Around line 8-25: Extract the duplicate RunCleanupLoop and CleanupInterval
into a shared utility function that accepts the interval as a parameter (e.g.,
create common.RunCleanupLoop(interval time.Duration, stop <-chan struct{},
cleanupFn func())), remove the local constant/duplicate RunCleanupLoop in both
packages, and update the callers in usage and auditlog to call
common.RunCleanupLoop(CleanupInterval, stop, cleanupFn) (or pass their existing
interval constant) so both packages use the single shared implementation; ensure
you keep the initial immediate cleanup call and ticker.Stop defer behavior in
the new common function.

In `@internal/usage/extractor.go`:
- Around line 31-34: The code assigns resp.Usage.RawUsage directly to
entry.RawData which can lead to races if the source map is mutated after Write
because entries are enqueued asynchronously; fix by making a defensive deep copy
of the map before assigning (for every occurrence where resp.Usage.RawUsage ->
entry.RawData is set, including the occurrences around the blocks at lines
similar to the ones shown and the other spots referenced) so entry.RawData owns
its own map instance rather than referencing the original resp.Usage.RawUsage.

In `@internal/usage/logger.go`:
- Around line 51-139: The Write path can still panic if l.buffer is closed
concurrently; make Close idempotent and block until in-flight Write calls finish
by adding a write-tracking WaitGroup and a close guard: introduce e.g.
l.writesWg (sync.WaitGroup) and l.closeOnce (sync.Once) or l.closeMu
(sync.Mutex)/RWMutex, update Write to take a read lock or check under the close
guard, call l.writesWg.Add(1) before attempting to send and defer
l.writesWg.Done(); if closed return without sending; update Close to use the
close guard or closeOnce to only close l.done once, set l.closed, then wait for
l.writesWg.Wait() and then wait for l.wg.Wait() (flushLoop) before closing the
store; reference functions/fields: Write, Close, flushLoop, l.closed, l.buffer,
l.done, l.wg, and add l.writesWg and l.closeOnce/closeMu as needed.

In `@internal/usage/store_mongodb.go`:
- Around line 123-145: The error handling after s.collection.InsertMany should
use errors.As to detect a wrapped mongo.BulkWriteException instead of a direct
type assertion; update the block that currently does "if bulkErr, ok :=
err.(mongo.BulkWriteException); ok { ... }" to use var bulkErr
mongo.BulkWriteException and errors.As(err, &bulkErr) so partial write detection
and logging (slog.Warn, usagePartialWriteFailures.Inc, and returning
&PartialWriteError{... Cause: bulkErr}) still occur for wrapped errors, and add
the "errors" import if missing; apply the same pattern used in
internal/auditlog/store_mongodb.go for consistency.

In `@internal/usage/store_postgresql.go`:
- Around line 67-76: The PostgreSQLStore currently always allocates stopCleanup
even when retentionDays <= 0; change the constructor to only create and assign
stopCleanup when retentionDays > 0 and start the goroutine, otherwise leave
stopCleanup nil (or zero value). Locate the PostgreSQLStore struct instantiation
(PostgreSQLStore) and the RunCleanupLoop call and condition on retentionDays to
perform both the make(chan struct{}) assignment and the go RunCleanupLoop(...)
invocation only when retentionDays > 0 so the unused channel isn't allocated.
- Around line 123-159: writeBatchLarge currently opens a transaction but still
calls tx.Exec per row (tx.Exec loop), which negates batch performance and also
collects insert errors yet proceeds to tx.Commit; change it to perform a true
batch insert using pgx.Batch (create a pgx.Batch, Queue the INSERT for each
UsageEntry, execute via s.pool.SendBatch or tx.SendBatch and read results) or
use tx.CopyFrom with pgx.CopyFromRows to insert all rows efficiently, and ensure
transactional semantics: if any batch/CopyFrom error occurs, call tx.Rollback
and return the error without committing (remove committing when errs were
collected), and replace the per-row error collection logic with handling the
batch/CopyFrom error result. Reference symbols: writeBatchLarge, tx.Exec
(remove), pgx.Batch / tx.CopyFrom, tx.Commit, tx.Rollback.

In `@internal/usage/store_sqlite.go`:
- Around line 167-171: The cleanup query uses time.RFC3339 but entries are
written using time.RFC3339Nano (causing incorrect string comparisons); update
the cutoff generation in the cleanup path (where cutoff is set before
s.db.Exec("DELETE FROM usage WHERE timestamp < ?", cutoff)) to use
time.RFC3339Nano instead of time.RFC3339 so the stored timestamps and the cutoff
use the same nanosecond precision.

In `@internal/usage/stream_wrapper.go`:
- Around line 41-52: The rolling buffer in the Write path currently calls
w.buffer.Reset() which doesn't shrink the backing array, so when trimming to
SSEBufferSize you must reallocate a new smaller buffer to cap memory; modify the
trim branch (where w.buffer.Len() > SSEBufferSize and you compute data :=
w.buffer.Bytes()) to create a fresh buffer of size SSEBufferSize (or a
bytes.NewBuffer with the sliced tail) and replace w.buffer with it (or copy the
tail into a new bytes.Buffer) instead of Reset()+Write(), ensuring capacity is
limited while preserving the last SSEBufferSize bytes.
- Around line 132-191: The code currently leaves totalTokens at 0 when
"total_tokens" is missing, undercounting usage; update the logic after
extracting inputTokens, outputTokens, totalTokens from usageMap to set
totalTokens = inputTokens + outputTokens when totalTokens == 0 and (inputTokens
> 0 || outputTokens > 0). Keep the existing rawData handling and call to
ExtractFromSSEUsage(providerID, inputTokens, outputTokens, totalTokens, rawData,
w.requestID, model, w.provider, w.endpoint) so the derived totalTokens is passed
through.
- Around line 104-130: The extractUsageFromJSON function in StreamUsageWrapper
currently unmarshals into map[string]interface{}; change it to unmarshal into
strongly-typed structs (e.g., SSEChunk struct with ID, Model, Usage
json.RawMessage fields and a UsagePayload struct with Token fields as
json.Number or *int64) inside StreamUsageWrapper.extractUsageFromJSON, then
decode UsagePayload to populate and return a UsageEntry (preserve any
provider-specific remaining data into UsageEntry.RawData as raw JSON); ensure
model override logic still uses SSEChunk.Model when present and convert
json.Number to int safely for token counts.

In `@internal/usage/usage_test.go`:
- Around line 44-85: Replace the fixed time.Sleep in TestLogger with a polling
loop that repeatedly checks store.getEntries() until the expected 5 entries
appear or a timeout elapses; locate the TestLogger test that constructs logger
via NewLogger, writes entries with logger.Write and currently does
time.Sleep(200*time.Millisecond), and change it to poll (using time.After for
overall timeout and time.Tick or short sleeps) to assert len(entries)==5 or fail
if timeout reached, then continue to Close() the logger and verify store.closed
as before.

In `@CLAUDE.md`:
- Around line 208-236: Add a single clarifying sentence to the "Manual Testing
with Docker" section stating that Docker Compose is optional and intended only
for manual storage-backend validation—not for running automated E2E or unit
tests—and that automated E2E tests must remain in-process without Docker; insert
this sentence near the examples that show STORAGE_TYPE, POSTGRES_URL and
MONGODB_URL so readers understand the distinction between manual validation and
in-process test suites.

In `@FUTURE_ARCHITECTURE.md`:
- Line 1: Add a top-level heading and specify the fenced-code language: insert a
heading "Future Architecture" at the top of FUTURE_ARCHITECTURE.md and change
the opening fence from an untyped "```" to "```text" and replace the malformed
closing "-```" with a proper closing "```"; apply the same change wherever an
untyped or malformed fenced block occurs (e.g., the other occurrence referenced
as "123-123").

In `@internal/core/types.go`:
- Around line 59-64: The Usage struct exposes RawUsage as map[string]any which
weakens API payload typing; change RawUsage to json.RawMessage to preserve
provider-specific raw bytes while keeping strong typing, update the Usage type
declaration (field RawUsage) to use json.RawMessage and ensure encoding/json is
imported, and then update any functions that marshal/unmarshal or assign to
Usage.RawUsage to handle raw JSON (e.g., pass through or
json.Marshal/json.RawMessage conversions) so existing
serialization/deserialization behavior is preserved.

In `@internal/usage/factory.go`:
- Around line 130-139: The defaults for storage type and paths are hardcoded;
replace the literal values (".cache/gomodel.db" and "gomodel") with shared
constants or getters from the storage/config package and fall back to storage
package defaults where available: update the initialization logic that sets
storageCfg.Type (currently comparing to storage.TypeSQLite),
storageCfg.SQLite.Path, and storageCfg.MongoDB.Database to use exported
constants (e.g., storage.DefaultSQLitePath, storage.DefaultMongoDatabase) or
call a storage.Defaults() helper so defaults remain single-sourced and cannot
drift.
- Around line 66-71: When createUsageStore(store, cfg.Usage.RetentionDays)
returns an error, the subsequent call to store.Close() currently ignores any
error; change the cleanup path in the block that handles the error to capture
the result of store.Close(), then either log it (using the existing logger in
scope) or wrap/aggregate it with the original createUsageStore error before
returning so cleanup failures aren’t lost; update the code around
createUsageStore, usageStore variable handling, and the store.Close() call to
return or log both errors together.
- Around line 23-41: The "Safe to call multiple times" comment is incorrect
because Logger.Close calls close(l.done) and will panic on a second call; either
remove or correct the comment or make Close idempotent: add a guarded closed
flag and mutex to both Result and the Logger implementation (check the closed
flag before calling Logger.Close, Storage.Close or closing l.done, set the flag
under lock after performing close operations) so repeated calls return nil
instead of closing channels twice; update the comment accordingly or remove it
if you implement the guard.

In `@internal/usage/store_sqlite.go`:
- Around line 58-70: The indexes list in the usage creation snippet (the indexes
slice and subsequent loop using db.Exec) omits an index on the endpoint column;
add "CREATE INDEX IF NOT EXISTS idx_usage_endpoint ON usage(endpoint)" to the
indexes slice so the for _, idx := range indexes { if _, err := db.Exec(idx) {
... } } loop will create it, ensuring queries that filter by endpoint are
indexed (reference the indexes variable, idx_usage_endpoint, and the db.Exec
call).

In `@internal/usage/usage.go`:
- Around line 49-55: The RawData field in the Usage struct currently uses
map[string]any; replace it with a typed struct (e.g., RawUsageData) that
contains optional, provider-specific sub-structs/fields (e.g., OpenAI,
Anthropic, Gemini) with proper json/bson tags and pointer types to keep fields
optional, then update the Usage.RawData field signature to use this new type;
ensure all code paths that read/write Usage.RawData
(serialization/deserialization, DB persistence and any unmarshalling code) are
updated to the new struct shape and handle backward compatibility (e.g.,
implement custom UnmarshalJSON/UnmarshalBSON or a migration helper to convert
existing map payloads into the typed RawUsageData).

In @.claude/settings.local.json:
- Around line 16-18: The permission entry Bash(mongosh:*) is too broad — replace
it with a least‑privilege alternative: either change Bash(mongosh:*) to require
confirmation (move it to an "ask" scope) or restrict it to explicit
subcommands/targets (e.g., list only the exact mongosh actions needed such as
count/find/aggregate or specific database/collection identifiers) so arbitrary
shell commands cannot be executed; update the settings entry accordingly and add
a brief comment explaining why the narrower scope or "ask" mode was chosen.

In `@internal/providers/gemini/gemini.go`:
- Around line 78-81: The code forwards a context request ID using
core.GetRequestID and sets header via req.Header.Set("X-Goog-Request-Id", ...)
even though Gemini may not accept that header; update the behavior to either (A)
verify Gemini acceptance and keep using "X-Goog-Request-Id" if confirmed, or (B)
change to a standard tracing header by replacing the header key with
"X-Request-Id" (or add both headers) so request tracing works; modify the logic
around core.GetRequestID(req.Context()) and req.Header.Set to implement the
chosen header(s) and ensure tests/logs reflect the header name change.

In `@internal/providers/openai/openai.go`:
- Around line 61-64: Replace the incorrect header "X-Request-ID" with OpenAI's
expected "X-Client-Request-Id" when forwarding the request ID from context
(where core.GetRequestID(req.Context()) is used); additionally validate the
request ID for ASCII-only characters and a maximum length of 512 bytes and only
set the header if the value passes validation (otherwise omit it) to avoid
triggering OpenAI 400 errors.

In `@CLAUDE.md`:
- Line 81: Update the phrasing on the line that reads "requires initialized
registry—check `ModelCount() > 0`" to use correct grammar; for example change it
to "requires an initialized registry—check `ModelCount() > 0`" or "requires the
registry to be initialized—check `ModelCount() > 0`" so the sentence reads
naturally.
- Line 9: Replace the bare URL "https://github.com/ENTERPILOT/GOModel" in the
Module line with a markdown link; e.g., update the line containing `**Module:**
`gomodel` | **Go:** 1.24.0 | **Repo:** https://github.com/ENTERPILOT/GOModel` to
use a labeled link such as `**Module:** `gomodel` | **Go:** 1.24.0 | **Repo:**
[GOModel](https://github.com/ENTERPILOT/GOModel)` so the URL is formatted as a
proper markdown link and avoids linter warnings.
- Around line 52-62: The fenced code block in the CLAUDE.md snippet (the block
beginning with ```) is missing a language specifier causing a markdown linter
warning; update that fenced block to include a language like text or plaintext
(e.g., change the opening fence from ``` to ```text) so the directory listing
block is properly marked and the linter warning is resolved.

In `@internal/providers/openai/openai_test.go`:
- Around line 753-809: Add tests for control characters to
TestIsValidClientRequestID by including cases like "\x00", "\t", and "\x7F"
(expecting invalid) to document handling of non-printable ASCII; and add an
integration test for setHeaders that constructs a provider via
NewWithHTTPClient, creates an http.Request with a context set via
core.WithRequestID, calls provider.setHeaders(req) and asserts the
"X-Client-Request-Id" header is set to the request ID for valid IDs and absent
for empty/invalid IDs (reference functions: isValidClientRequestID, setHeaders,
NewWithHTTPClient, core.WithRequestID, header "X-Client-Request-Id").