@warlock.js/context 5.34.1 → 5.34.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/context` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Merge package orientation into the grouped skill index and remove the duplicate overview topic; preserve that orientation in generated LLM projections.
+
 ## 5.32.0 - 2026-10-18
 
 ### Changed

package/llms-full.txt

@@ -4,6 +4,65 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/context/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
+## Package orientation
+
+---
+description: 'Typed request-scoped context on Node AsyncLocalStorage, so data (user, tenant, trace id, transaction) flows through awaits without parameter threading. Exports `Context`, `contextManager`, `ContextManager`. Use for: "share the current user or tenant across async calls", "request-scoped storage", "AsyncLocalStorage wrapper", "run several contexts together", "avoid passing data through every function". Not this package: cross-request state → @warlock.js/cache or a database; HTTP request/response objects → @warlock.js/core.'
+---
+
+# @warlock.js/context
+
+A thin typed wrapper over `AsyncLocalStorage`. Each `Context<TStore>` subclass declares its store shape and how `buildStore` creates it; the store lives for the scope and propagates through every `await` inside. `contextManager` runs several contexts together. Zero dependencies; the framework uses it internally for request, user and tenant.
+
+## The 80% path
+
+1. Use this index for orientation and choose a task below.
+2. Subclass `Context`, implement `buildStore`, read with `get` / `set` anywhere down the call tree: `define-context.md`.
+3. Wrap work with `run(store, callback)`, or `enter(store)` for middleware that cannot wrap a callback: `define-context.md`.
+4. With two or more active contexts, register them on `contextManager` and use `runAll` / `enterAll`: `orchestrate-contexts.md`.
+
+## Conventions and pitfalls
+
+- Outside a `run`/`enter` scope there is no store; guard with `hasContext` when code may run unscoped.
+- `enter` leaks until cleared; pair `enterAll` with `clearAll` at the end of the request.
+- Worker threads do not share the store; serialize data across and re-enter.
+- Context is not shared state: it vanishes with the scope.
+- One context in a cooperative framework needs no manager; use plain `run`.
+
+## When to reach for it
+
+- You have request-scoped data (user, tenant, trace id, db transaction) that you'd otherwise thread through every function as a parameter. One `userContext.get("userId")` anywhere down the call tree replaces five layers of plumbing.
+- You're inside a `@warlock.js/*` project and want consistent context handling across modules. The framework already uses this package internally for request + user + tenant contexts.
+- You'd reach for **cls-hooked**, **nest-context**, or a bare `AsyncLocalStorage<T>` and want a typed wrapper with `run` / `enter` / `update` / `get` / `set` semantics out of the box.
+
+Skip if your call chain is a single function with no `await` boundaries — just pass the data as a parameter. Skip if you need cross-request shared state — that's a cache or database, not a context.
+
+## What it is in one sentence
+
+Each `Context<TStore>` subclass declares a typed store shape and what payload builds it; the framework uses Node's `AsyncLocalStorage` under the hood so the store propagates through every `await` inside the scope and disappears when the scope ends.
+
+## Two operating modes — when to pick which
+
+| Situation                                                               | Reach for                                                  |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Framework gives you a callback to wrap                                  | `context.run(store, callback)`                             |
+| Framework expects middleware that returns synchronously (Express, etc.) | `context.enter(store)`                                     |
+| You have 2+ contexts active for the same request                        | `contextManager.runAll(stores, callback)`                  |
+| Middleware-style with 2+ contexts                                       | `contextManager.enterAll(stores)` then `clearAll()` at end |
+| You only have one context and the framework cooperates                  | Single `context.run(...)`. Skip the manager.               |
+
+## What this package deliberately doesn't do
+
+- **Persist data across requests.** AsyncLocalStorage dies with the scope. For cross-request state, reach for `@warlock.js/cache` or a database.
+- **Cross-thread context.** Worker threads don't share AsyncLocalStorage with the main thread. Serialize the data you need across the boundary and re-enter on the other side.
+- **Browser context.** Server-side only. The browser equivalent is React Context or a state library.
+- **Implicit context for non-async code.** If your call stack has no `await`, the storage works but there's no propagation benefit — just pass the value as a parameter.
+
+## See also
+
+- The `warlock-js-core` skill index — the parent framework; `context` is one of its foundation packages.
+
+
 ## define-context  `@warlock.js/context/define-context/SKILL.md`
 
 ---
@@ -328,75 +387,3 @@ async function handleRequest(req: any, res: any) {
 - Don't expect `enterAll()` to auto-clean. It's a one-way setup — pair with `clearAll()` at the end of the request, or just use `runAll` when you can.
 
 
-## overview  `@warlock.js/context/overview/SKILL.md`
-
----
-name: overview
-description: "@warlock.js/context overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/context` — overview
-
-Two-file package: a typed wrapper over Node's `AsyncLocalStorage` and a singleton that runs several of them together. That's it. The entire surface fits in two skills below — most callers only need the first one.
-
-## When to reach for it
-
-- You have request-scoped data (user, tenant, trace id, db transaction) that you'd otherwise thread through every function as a parameter. One `userContext.get("userId")` anywhere down the call tree replaces five layers of plumbing.
-- You're inside a `@warlock.js/*` project and want consistent context handling across modules. The framework already uses this package internally for request + user + tenant contexts.
-- You'd reach for `cls-hooked`, `nest-context`, or a bare `AsyncLocalStorage<T>` and want a typed wrapper with `run` / `enter` / `update` / `get` / `set` semantics out of the box.
-
-Skip if your call chain is a single function with no `await` boundaries — just pass the data as a parameter. Skip if you need cross-request shared state — that's a cache or database, not a context.
-
-## What it is in one sentence
-
-Each `Context<TStore>` subclass declares a typed store shape and what payload builds it; the framework uses Node's `AsyncLocalStorage` under the hood so the store propagates through every `await` inside the scope and disappears when the scope ends.
-
-## Skills index
-
-Two task skills cover everything. The first one is the daily-use one; the second is for when you have multiple contexts active at the same time.
-
-### `define-context`
-
-Extend `Context<TStore>` to declare what your context stores and how it's
-built. Implement `buildStore(payload?)`; use `run` / `enter` / `update` /
-`get` / `set` / `getStore` / `clear` / `hasContext` to interact with the
-store from anywhere in the async scope.
-
-Load when sharing data (user, tenant, trace id) across async calls
-without threading it through every function — i.e. ~90% of the time you
-use this package.
-
-### `orchestrate-contexts`
-
-Register multiple `Context<TStore>` instances on the `contextManager`
-singleton and run them all together with a single call. Covers
-`register` / `unregister`, `buildStores`, `runAll` / `enterAll`,
-`clearAll`, `getContext` / `hasContext`.
-
-Load when several contexts apply to the same scope (request + database
-
-- trace + tenant) and you'd otherwise nest `run()` calls by hand.
-
-## Two operating modes — when to pick which
-
-| Situation                                                               | Reach for                                                  |
-| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
-| Framework gives you a callback to wrap                                  | `context.run(store, callback)`                             |
-| Framework expects middleware that returns synchronously (Express, etc.) | `context.enter(store)`                                     |
-| You have 2+ contexts active for the same request                        | `contextManager.runAll(stores, callback)`                  |
-| Middleware-style with 2+ contexts                                       | `contextManager.enterAll(stores)` then `clearAll()` at end |
-| You only have one context and the framework cooperates                  | Single `context.run(...)`. Skip the manager.               |
-
-## What this package deliberately doesn't do
-
-- **Persist data across requests.** AsyncLocalStorage dies with the scope. For cross-request state, reach for `@warlock.js/cache` or a database.
-- **Cross-thread context.** Worker threads don't share AsyncLocalStorage with the main thread. Serialize the data you need across the boundary and re-enter on the other side.
-- **Browser context.** Server-side only. The browser equivalent is React Context or a state library.
-- **Implicit context for non-async code.** If your call stack has no `await`, the storage works but there's no propagation benefit — just pass the value as a parameter.
-
-## See also
-
-- The `overview` topic of the `warlock-js-core` skill — the parent framework; `context` is one of its foundation packages.
-- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this `overview` topic becomes the front-door skill in `.claude/skills/warlock-js-context-overview/`.
-
-

package/llms.txt

@@ -6,6 +6,6 @@
 
 ## Skills
 
+- [Package orientation](@warlock.js/context/skills/index.md): Typed request-scoped context on Node AsyncLocalStorage, so data (user, tenant, trace id, transaction) flows through awaits without parameter threading. Exports `Context`, `contextManager`, `ContextManager`. Use for: "share the current user or tenant across async calls", "request-scoped storage", "AsyncLocalStorage wrapper", "run several contexts together", "avoid passing data through every function". Not this package: cross-request state → @warlock.js/cache or a database; HTTP request/response objects → @warlock.js/core.
 - [define-context](@warlock.js/context/define-context/SKILL.md): Extend Context<TStore> to define an AsyncLocalStorage-backed typed context — implement buildStore, use run / enter / update / get / set / getStore / clear / hasContext. Triggers: `Context`, `Context<TStore>`, `buildStore`, `run`, `enter`, `update`, `get`, `set`, `getStore`, `clear`, `hasContext`; "share user/tenant/trace id across async calls", "AsyncLocalStorage typed wrapper", "request-scoped store without thread-through"; typical import `import { Context } from "@warlock.js/context"`. Skip: orchestrating multiple contexts — the `orchestrate-contexts` topic; native `AsyncLocalStorage`, `cls-hooked`, `nest-context`, React Context.
 - [orchestrate-contexts](@warlock.js/context/orchestrate-contexts/SKILL.md): Orchestrate multiple Context<TStore> instances via the contextManager singleton — register, buildStores, runAll, enterAll, clearAll. Triggers: `contextManager`, `register`, `buildStores`, `runAll`, `enterAll`, `clearAll`, `unregister`, `getContext`, `hasContext`; "run multiple contexts active for the same scope", "register contexts at boot", "avoid nested run() calls for request + database + tenant"; typical import `import { contextManager } from "@warlock.js/context"`. Skip: defining a single context class — the `define-context` topic; native `AsyncLocalStorage` nesting, `cls-hooked` namespaces.
-- [overview](@warlock.js/context/overview/SKILL.md): @warlock.js/context overview for orientation and choosing the focused skill for the task.

package/package.json

@@ -25,7 +25,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "5.34.1",
+  "version": "5.34.2",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/index.md

@@ -8,7 +8,7 @@ A thin typed wrapper over `AsyncLocalStorage`. Each `Context<TStore>` subclass d
 
 ## The 80% path
 
-1. Orient with `overview.md`.
+1. Use this index for orientation and choose a task below.
 2. Subclass `Context`, implement `buildStore`, read with `get` / `set` anywhere down the call tree: `define-context.md`.
 3. Wrap work with `run(store, callback)`, or `enter(store)` for middleware that cannot wrap a callback: `define-context.md`.
 4. With two or more active contexts, register them on `contextManager` and use `runAll` / `enterAll`: `orchestrate-contexts.md`.
@@ -20,3 +20,36 @@ A thin typed wrapper over `AsyncLocalStorage`. Each `Context<TStore>` subclass d
 - Worker threads do not share the store; serialize data across and re-enter.
 - Context is not shared state: it vanishes with the scope.
 - One context in a cooperative framework needs no manager; use plain `run`.
+
+## When to reach for it
+
+- You have request-scoped data (user, tenant, trace id, db transaction) that you'd otherwise thread through every function as a parameter. One `userContext.get("userId")` anywhere down the call tree replaces five layers of plumbing.
+- You're inside a `@warlock.js/*` project and want consistent context handling across modules. The framework already uses this package internally for request + user + tenant contexts.
+- You'd reach for **cls-hooked**, **nest-context**, or a bare `AsyncLocalStorage<T>` and want a typed wrapper with `run` / `enter` / `update` / `get` / `set` semantics out of the box.
+
+Skip if your call chain is a single function with no `await` boundaries — just pass the data as a parameter. Skip if you need cross-request shared state — that's a cache or database, not a context.
+
+## What it is in one sentence
+
+Each `Context<TStore>` subclass declares a typed store shape and what payload builds it; the framework uses Node's `AsyncLocalStorage` under the hood so the store propagates through every `await` inside the scope and disappears when the scope ends.
+
+## Two operating modes — when to pick which
+
+| Situation                                                               | Reach for                                                  |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Framework gives you a callback to wrap                                  | `context.run(store, callback)`                             |
+| Framework expects middleware that returns synchronously (Express, etc.) | `context.enter(store)`                                     |
+| You have 2+ contexts active for the same request                        | `contextManager.runAll(stores, callback)`                  |
+| Middleware-style with 2+ contexts                                       | `contextManager.enterAll(stores)` then `clearAll()` at end |
+| You only have one context and the framework cooperates                  | Single `context.run(...)`. Skip the manager.               |
+
+## What this package deliberately doesn't do
+
+- **Persist data across requests.** AsyncLocalStorage dies with the scope. For cross-request state, reach for `@warlock.js/cache` or a database.
+- **Cross-thread context.** Worker threads don't share AsyncLocalStorage with the main thread. Serialize the data you need across the boundary and re-enter on the other side.
+- **Browser context.** Server-side only. The browser equivalent is React Context or a state library.
+- **Implicit context for non-async code.** If your call stack has no `await`, the storage works but there's no propagation benefit — just pass the value as a parameter.
+
+## See also
+
+- The `warlock-js-core` skill index — the parent framework; `context` is one of its foundation packages.

package/skills/overview/SKILL.md

@@ -1,68 +0,0 @@
----
-name: overview
-description: "@warlock.js/context overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/context` — overview
-
-Two-file package: a typed wrapper over Node's `AsyncLocalStorage` and a singleton that runs several of them together. That's it. The entire surface fits in two skills below — most callers only need the first one.
-
-## When to reach for it
-
-- You have request-scoped data (user, tenant, trace id, db transaction) that you'd otherwise thread through every function as a parameter. One `userContext.get("userId")` anywhere down the call tree replaces five layers of plumbing.
-- You're inside a `@warlock.js/*` project and want consistent context handling across modules. The framework already uses this package internally for request + user + tenant contexts.
-- You'd reach for `cls-hooked`, `nest-context`, or a bare `AsyncLocalStorage<T>` and want a typed wrapper with `run` / `enter` / `update` / `get` / `set` semantics out of the box.
-
-Skip if your call chain is a single function with no `await` boundaries — just pass the data as a parameter. Skip if you need cross-request shared state — that's a cache or database, not a context.
-
-## What it is in one sentence
-
-Each `Context<TStore>` subclass declares a typed store shape and what payload builds it; the framework uses Node's `AsyncLocalStorage` under the hood so the store propagates through every `await` inside the scope and disappears when the scope ends.
-
-## Skills index
-
-Two task skills cover everything. The first one is the daily-use one; the second is for when you have multiple contexts active at the same time.
-
-### `define-context`
-
-Extend `Context<TStore>` to declare what your context stores and how it's
-built. Implement `buildStore(payload?)`; use `run` / `enter` / `update` /
-`get` / `set` / `getStore` / `clear` / `hasContext` to interact with the
-store from anywhere in the async scope.
-
-Load when sharing data (user, tenant, trace id) across async calls
-without threading it through every function — i.e. ~90% of the time you
-use this package.
-
-### `orchestrate-contexts`
-
-Register multiple `Context<TStore>` instances on the `contextManager`
-singleton and run them all together with a single call. Covers
-`register` / `unregister`, `buildStores`, `runAll` / `enterAll`,
-`clearAll`, `getContext` / `hasContext`.
-
-Load when several contexts apply to the same scope (request + database
-
-- trace + tenant) and you'd otherwise nest `run()` calls by hand.
-
-## Two operating modes — when to pick which
-
-| Situation                                                               | Reach for                                                  |
-| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
-| Framework gives you a callback to wrap                                  | `context.run(store, callback)`                             |
-| Framework expects middleware that returns synchronously (Express, etc.) | `context.enter(store)`                                     |
-| You have 2+ contexts active for the same request                        | `contextManager.runAll(stores, callback)`                  |
-| Middleware-style with 2+ contexts                                       | `contextManager.enterAll(stores)` then `clearAll()` at end |
-| You only have one context and the framework cooperates                  | Single `context.run(...)`. Skip the manager.               |
-
-## What this package deliberately doesn't do
-
-- **Persist data across requests.** AsyncLocalStorage dies with the scope. For cross-request state, reach for `@warlock.js/cache` or a database.
-- **Cross-thread context.** Worker threads don't share AsyncLocalStorage with the main thread. Serialize the data you need across the boundary and re-enter on the other side.
-- **Browser context.** Server-side only. The browser equivalent is React Context or a state library.
-- **Implicit context for non-async code.** If your call stack has no `await`, the storage works but there's no propagation benefit — just pass the value as a parameter.
-
-## See also
-
-- The `overview` topic of the `warlock-js-core` skill — the parent framework; `context` is one of its foundation packages.
-- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this `overview` topic becomes the front-door skill in `.claude/skills/warlock-js-context-overview/`.