@oh-my-pi/pi-coding-agent 15.5.15 → 15.7.0

package/src/config/settings-schema.ts

@@ -1,6 +1,24 @@
 import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
 import { TASK_SIMPLE_MODES } from "../task/simple-mode";
 import { getThinkingLevelMetadata } from "../thinking";
+import {
+	TINY_MODEL_DEVICE_DEFAULT,
+	TINY_MODEL_DEVICE_SETTING_OPTIONS,
+	TINY_MODEL_DEVICE_SETTING_VALUES,
+} from "../tiny/device";
+import {
+	TINY_MODEL_DTYPE_DEFAULT,
+	TINY_MODEL_DTYPE_SETTING_OPTIONS,
+	TINY_MODEL_DTYPE_SETTING_VALUES,
+} from "../tiny/dtype";
+import {
+	ONLINE_MEMORY_MODEL_KEY,
+	ONLINE_TINY_TITLE_MODEL_KEY,
+	TINY_MEMORY_MODEL_OPTIONS,
+	TINY_MEMORY_MODEL_VALUES,
+	TINY_TITLE_MODEL_OPTIONS,
+	TINY_TITLE_MODEL_VALUES,
+} from "../tiny/models";
 import { EDIT_MODES } from "../utils/edit-mode";
 
 /** Unified settings schema - single source of truth for all settings.
@@ -235,6 +253,7 @@ export const SETTINGS_SCHEMA = {
 	// General settings (no UI)
 	// ────────────────────────────────────────────────────────────────────────
 	lastChangelogVersion: { type: "string", default: undefined },
+	setupVersion: { type: "number", default: 0 },
 
 	// Auth broker — credentials proxied through a remote `omp auth-broker serve`
 	// host. Hidden from the UI; populate via env vars or hand-edited config.yml.
@@ -991,6 +1010,16 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"startup.setupWizard": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "interaction",
+			label: "Setup Wizard",
+			description: "Show newly added onboarding steps once per setup version",
+		},
+	},
+
 	"startup.checkUpdate": {
 		type: "boolean",
 		default: true,
@@ -1292,23 +1321,192 @@ export const SETTINGS_SCHEMA = {
 	"memories.summaryInjectionTokenLimit": { type: "number", default: 5000 },
 
 	// Memory backend selector — picks between local memories pipeline,
-	// Hindsight remote memory, or off. Legacy `memories.enabled` keeps gating
-	// the local backend; see config/settings.ts migration for details.
+	// Mnemosyne local SQLite, Hindsight remote memory, or off. Legacy
+	// `memories.enabled` keeps gating the local backend; see config/settings.ts
+	// migration for details.
 	"memory.backend": {
 		type: "enum",
-		values: ["off", "local", "hindsight"] as const,
+		values: ["off", "local", "hindsight", "mnemosyne"] as const,
 		default: "off",
 		ui: {
 			tab: "memory",
 			label: "Memory Backend",
-			description: "Off, local memory pipeline, or Hindsight remote memory",
+			description: "Off, local summary pipeline, Mnemosyne SQLite, or Hindsight remote memory",
 			options: [
 				{ value: "off", label: "Off", description: "No memory subsystem runs" },
 				{ value: "local", label: "Local", description: "Local rollout summarisation pipeline (memory_summary.md)" },
 				{ value: "hindsight", label: "Hindsight", description: "Vectorize Hindsight remote memory service" },
+				{
+					value: "mnemosyne",
+					label: "Mnemosyne",
+					description: "Local SQLite recall/retain backend with optional embeddings",
+				},
+			],
+		},
+	},
+
+	// Mnemosyne local SQLite memory backend.
+	"mnemosyne.dbPath": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne DB Path",
+			description: "Optional SQLite DB path. Defaults to the agent memories directory.",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.bank": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Bank",
+			description: "Optional shared bank base name. Per-project modes derive project-local banks from it.",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.scoping": {
+		type: "enum",
+		values: ["global", "per-project", "per-project-tagged"] as const,
+		default: "per-project",
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Scoping",
+			description:
+				"global = one shared bank; per-project = isolated bank per cwd; per-project-tagged = project-local writes plus global recall visibility",
+			options: [
+				{
+					value: "global",
+					label: "Global",
+					description: "One shared Mnemosyne bank for every project",
+				},
+				{
+					value: "per-project",
+					label: "Per project",
+					description: "Project-local Mnemosyne bank per cwd basename",
+				},
+				{
+					value: "per-project-tagged",
+					label: "Per project (tagged)",
+					description: "Write to a project-local bank but merge project + shared recall results",
+				},
+			],
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.autoRecall": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Auto Recall",
+			description: "Recall local memories into the first turn of each session",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.autoRetain": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Auto Retain",
+			description: "Retain completed conversation turns into local Mnemosyne memory",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.noEmbeddings": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Disable Embeddings",
+			description: "Force deterministic FTS-only recall instead of vector embeddings",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.embeddingModel": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Embedding Model",
+			description: "Optional embedding model override passed to Mnemosyne",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.embeddingApiUrl": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Embedding API URL",
+			description: "Optional OpenAI-compatible embedding endpoint passed to Mnemosyne",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.embeddingApiKey": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne Embedding API Key",
+			description: "Optional embedding API key passed to Mnemosyne",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.llmMode": {
+		type: "enum",
+		values: ["none", "smol", "remote"] as const,
+		default: "smol",
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne LLM Mode",
+			description: "Use no LLM, the configured smol model, or a remote OpenAI-compatible endpoint",
+			condition: "mnemosyneActive",
+			options: [
+				{ value: "none", label: "None", description: "Disable Mnemosyne LLM-backed extraction" },
+				{ value: "smol", label: "Smol", description: "Use the configured pi-ai smol model" },
+				{ value: "remote", label: "Remote", description: "Use the Mnemosyne remote LLM settings below" },
 			],
 		},
 	},
+	"mnemosyne.llmBaseUrl": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne LLM Base URL",
+			description: "Optional OpenAI-compatible LLM endpoint for Mnemosyne remote mode",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.llmApiKey": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne LLM API Key",
+			description: "Optional LLM API key for Mnemosyne remote mode",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.llmModel": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "memory",
+			label: "Mnemosyne LLM Model",
+			description: "Optional LLM model name for Mnemosyne remote mode",
+			condition: "mnemosyneActive",
+		},
+	},
+	"mnemosyne.retainEveryNTurns": { type: "number", default: 4 },
+	"mnemosyne.recallLimit": { type: "number", default: 8 },
+	"mnemosyne.recallContextTurns": { type: "number", default: 3 },
+	"mnemosyne.recallMaxQueryChars": { type: "number", default: 4000 },
+	"mnemosyne.injectionTokenLimit": { type: "number", default: 5000 },
+	"mnemosyne.debug": { type: "boolean", default: false },
 
 	// Hindsight (https://hindsight.vectorize.io)
 	"hindsight.apiUrl": {
@@ -1517,6 +1715,26 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"ttsr.builtinRules": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "context",
+			label: "Builtin Rules",
+			description: "Load the default rules shipped with the agent (override individually with ttsr.disabledRules)",
+		},
+	},
+
+	"ttsr.disabledRules": {
+		type: "array",
+		default: [] as string[],
+		ui: {
+			tab: "context",
+			label: "Disabled Rules",
+			description: "Rule names to ignore entirely (applies to bundled defaults and your own rules)",
+		},
+	},
+
 	// ────────────────────────────────────────────────────────────────────────
 	// Editing
 	// ────────────────────────────────────────────────────────────────────────
@@ -1848,7 +2066,7 @@ export const SETTINGS_SCHEMA = {
 					value: "write",
 					label: "Write",
 					description:
-						"Auto-approve read-only and write tools; require confirmation for exec tools such as bash, eval, browser, task, recipe, and ssh.",
+						"Auto-approve read-only and write tools; require confirmation for exec tools such as bash, eval, browser, task, and ssh.",
 				},
 				{
 					value: "yolo",
@@ -2026,16 +2244,6 @@ export const SETTINGS_SCHEMA = {
 			description: "Enable the tts tool for xAI Grok Voice speech synthesis",
 		},
 	},
-	"recipe.enabled": {
-		type: "boolean",
-		default: true,
-		ui: {
-			tab: "tools",
-			label: "Recipe",
-			description:
-				"Enable the recipe tool when a justfile / package.json / Cargo.toml / Makefile / Taskfile is present",
-		},
-	},
 
 	"inspect_image.enabled": {
 		type: "boolean",
@@ -2727,6 +2935,54 @@ export const SETTINGS_SCHEMA = {
 			],
 		},
 	},
+	"providers.tinyModel": {
+		type: "enum",
+		values: TINY_TITLE_MODEL_VALUES,
+		default: ONLINE_TINY_TITLE_MODEL_KEY,
+		ui: {
+			tab: "providers",
+			label: "Tiny Model",
+			description: "Session-title model: online pi/smol by default, or a local on-device model",
+			options: TINY_TITLE_MODEL_OPTIONS,
+		},
+	},
+	"providers.tinyModelDevice": {
+		type: "enum",
+		values: TINY_MODEL_DEVICE_SETTING_VALUES,
+		default: TINY_MODEL_DEVICE_DEFAULT,
+		ui: {
+			tab: "providers",
+			label: "Tiny Model Device",
+			description:
+				"ONNX execution provider for local tiny models (titles + memory). Default picks DirectML on Windows, CUDA on Linux x64, CPU elsewhere. The PI_TINY_DEVICE env var overrides this.",
+			options: TINY_MODEL_DEVICE_SETTING_OPTIONS,
+		},
+	},
+	"providers.tinyModelDtype": {
+		type: "enum",
+		values: TINY_MODEL_DTYPE_SETTING_VALUES,
+		default: TINY_MODEL_DTYPE_DEFAULT,
+		ui: {
+			tab: "providers",
+			label: "Tiny Model Precision",
+			description:
+				"ONNX quantization/precision for local tiny models. Default uses each model's shipped dtype (q4); lower precision is faster, higher is more faithful. The PI_TINY_DTYPE env var overrides this.",
+			options: TINY_MODEL_DTYPE_SETTING_OPTIONS,
+		},
+	},
+	"providers.memoryModel": {
+		type: "enum",
+		values: TINY_MEMORY_MODEL_VALUES,
+		default: ONLINE_MEMORY_MODEL_KEY,
+		ui: {
+			tab: "memory",
+			label: "Memory Model",
+			description:
+				"Mnemosyne LLM for fact extraction + consolidation: online (smol/remote) by default, or a local on-device model",
+			condition: "mnemosyneActive",
+			options: TINY_MEMORY_MODEL_OPTIONS,
+		},
+	},
 
 	"providers.kimiApiFormat": {
 		type: "enum",
@@ -3097,6 +3353,10 @@ export interface TtsrSettings {
 	interruptMode: "never" | "prose-only" | "tool-only" | "always";
 	repeatMode: "once" | "after-gap";
 	repeatGap: number;
+	/** Bucketing-only (read by bucketRules, not the TtsrManager). */
+	builtinRules?: boolean;
+	/** Bucketing-only (read by bucketRules, not the TtsrManager). */
+	disabledRules?: string[];
 }
 
 export interface ExaSettings {

package/src/discovery/builtin-defaults.ts

@@ -0,0 +1,39 @@
+/**
+ * Builtin Defaults Provider
+ *
+ * Ships a curated set of default rules (mostly TTSR conventions) embedded into
+ * the binary. Registered at the lowest priority so any user/project/tool rule
+ * with the same `name` overrides the bundled copy (first-wins dedup by name).
+ *
+ * Users disable bundled rules three ways:
+ *   - flip `ttsr.builtinRules` off (drops the whole set),
+ *   - list a name in `ttsr.disabledRules` (drops one rule),
+ *   - define a same-named rule in any higher-priority source (overrides it).
+ * The first two are enforced in `bucketRules` (see capability/rule-buckets.ts).
+ */
+import { registerProvider } from "../capability";
+import { BUILTIN_DEFAULTS_PROVIDER_ID, type Rule, ruleCapability } from "../capability/rule";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { BUILTIN_RULE_SOURCES } from "./builtin-rules";
+import { buildRuleFromMarkdown, createSourceMeta } from "./helpers";
+
+const DISPLAY_NAME = "Builtin Defaults";
+// Lowest priority: every other rule provider wins a name conflict.
+const PRIORITY = 1;
+
+async function loadRules(_ctx: LoadContext): Promise<LoadResult<Rule>> {
+	const items = BUILTIN_RULE_SOURCES.map(({ name, content }) => {
+		const virtualPath = `${BUILTIN_DEFAULTS_PROVIDER_ID}:${name}.md`;
+		const source = createSourceMeta(BUILTIN_DEFAULTS_PROVIDER_ID, virtualPath, "user");
+		return buildRuleFromMarkdown(name, content, virtualPath, source, { ruleName: name });
+	});
+	return { items };
+}
+
+registerProvider<Rule>(ruleCapability.id, {
+	id: BUILTIN_DEFAULTS_PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Default rules shipped with the agent (disable via ttsr.builtinRules / ttsr.disabledRules)",
+	priority: PRIORITY,
+	load: loadRules,
+});

package/src/discovery/builtin-rules/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Bundled default rules shipped with the coding agent.
+ *
+ * Each markdown source is embedded via `with { type: "text" }` so it survives
+ * `bun build --compile` (the compiled binary ships no loose rule files; only
+ * the embedded text). The native source/tarball installs read the same modules.
+ *
+ * Registered by the lowest-priority `builtin-defaults` rule provider so any
+ * user/project/tool rule with the same name overrides the bundled copy.
+ */
+import rsBoxLeak from "./rs-box-leak.md" with { type: "text" };
+import rsFuturePrelude from "./rs-future-prelude.md" with { type: "text" };
+import rsLazylock from "./rs-lazylock.md" with { type: "text" };
+import rsMatchErgonomics from "./rs-match-ergonomics.md" with { type: "text" };
+import rsParkingLot from "./rs-parking-lot.md" with { type: "text" };
+import rsResultType from "./rs-result-type.md" with { type: "text" };
+import tsBareCatch from "./ts-bare-catch.md" with { type: "text" };
+import tsImportType from "./ts-import-type.md" with { type: "text" };
+import tsNoAny from "./ts-no-any.md" with { type: "text" };
+import tsNoDynamicImport from "./ts-no-dynamic-import.md" with { type: "text" };
+import tsNoReturnType from "./ts-no-return-type.md" with { type: "text" };
+import tsNoTinyFunctions from "./ts-no-tiny-functions.md" with { type: "text" };
+import tsPromiseWithResolvers from "./ts-promise-with-resolvers.md" with { type: "text" };
+import tsSetMap from "./ts-set-map.md" with { type: "text" };
+
+/** A bundled rule's stable name and raw markdown (frontmatter + body). */
+export interface BuiltinRuleSource {
+	name: string;
+	content: string;
+}
+
+/** All bundled default rules, ordered by name. */
+export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
+	{ name: "rs-box-leak", content: rsBoxLeak },
+	{ name: "rs-future-prelude", content: rsFuturePrelude },
+	{ name: "rs-lazylock", content: rsLazylock },
+	{ name: "rs-match-ergonomics", content: rsMatchErgonomics },
+	{ name: "rs-parking-lot", content: rsParkingLot },
+	{ name: "rs-result-type", content: rsResultType },
+	{ name: "ts-bare-catch", content: tsBareCatch },
+	{ name: "ts-import-type", content: tsImportType },
+	{ name: "ts-no-any", content: tsNoAny },
+	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
+	{ name: "ts-no-return-type", content: tsNoReturnType },
+	{ name: "ts-no-tiny-functions", content: tsNoTinyFunctions },
+	{ name: "ts-promise-with-resolvers", content: tsPromiseWithResolvers },
+	{ name: "ts-set-map", content: tsSetMap },
+];

package/src/discovery/builtin-rules/rs-box-leak.md

@@ -0,0 +1,48 @@
+---
+description: Never use Box::leak - it intentionally leaks memory
+condition: "Box::leak"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Never use `Box::leak` to satisfy a lifetime. It intentionally leaks the allocation for the rest of the process.
+
+## Why
+
+- The allocation is never freed.
+- It hides ownership bugs.
+- It turns lifetime errors into process lifetime growth.
+- It makes tests pass while production memory grows.
+
+## Use instead
+
+| Need | Use |
+| --- | --- |
+| Shared async/thread data | `Arc<T>` or owned values |
+| Global lazy state | `LazyLock<T>` or `OnceLock<T>` |
+| Text escaping a scope | `String` / `Arc<str>` |
+| `'static` callback | `move` closure with owned captures |
+| FFI pointer | Explicit owner that frees on drop |
+
+## Examples
+
+```rust
+// Bad — leaking to manufacture 'static.
+fn label(id: u64) -> &'static str {
+    Box::leak(Box::new(format!("item_{id}")))
+}
+
+// Good — return owned data.
+fn label(id: u64) -> String {
+    format!("item_{id}")
+}
+
+// Bad — leaking before spawn.
+let state = Box::leak(Box::new(state));
+tokio::spawn(async move { use_state(state) });
+
+// Good — share owned state.
+let state = Arc::new(state);
+tokio::spawn(async move { use_state(&state) });
+```
+
+If `Box::leak` looks necessary, fix ownership instead.

package/src/discovery/builtin-rules/rs-future-prelude.md

@@ -0,0 +1,23 @@
+---
+description: Use Future not std::future::Future - it's in the prelude
+condition: "std::future::Future"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use `Future` directly instead of `std::future::Future` in type positions.
+
+Rust 2024 includes `Future` in the standard prelude. Older editions can import it once with `use std::future::Future;`. Repeating the fully qualified path makes signatures harder to read without adding safety.
+
+## Examples
+
+```rust
+// Bad — fully qualified in every signature.
+fn fetch() -> impl std::future::Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn std::future::Future<Output = i32>>) { ... }
+
+// Good — use the prelude or one import.
+fn fetch() -> impl Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn Future<Output = i32>>) { ... }
+```
+
+Pre-2024 edition? Add `use std::future::Future;` at the top.

package/src/discovery/builtin-rules/rs-lazylock.md

@@ -0,0 +1,51 @@
+---
+description: Prefer std::sync::LazyLock over OnceLock and once_cell
+condition:
+  - "once_cell::"
+  - "OnceLock::new"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Prefer `std::sync::LazyLock` over `OnceLock` and the `once_cell` crate when the initializer is known at declaration time.
+
+`LazyLock` stores the cell and initializer together. There is no separate `init()` function, no repeated `get_or_init`, and no missing initialization path.
+
+## once_cell → std
+
+```rust
+// Before
+use once_cell::sync::Lazy;
+static CONFIG: Lazy<String> = Lazy::new(|| "value".to_string());
+
+// After
+use std::sync::LazyLock;
+static CONFIG: LazyLock<String> = LazyLock::new(|| "value".to_string());
+```
+
+## OnceLock → LazyLock
+
+```rust
+// Before — fixed initializer hidden in accessor.
+use std::sync::OnceLock;
+static SETTINGS: OnceLock<Settings> = OnceLock::new();
+fn settings() -> &'static Settings {
+    SETTINGS.get_or_init(Settings::load)
+}
+
+// After — initializer lives with the static.
+use std::sync::LazyLock;
+static SETTINGS: LazyLock<Settings> = LazyLock::new(Settings::load);
+```
+
+## Keep OnceLock when runtime input is required
+
+```rust
+use std::sync::OnceLock;
+static DATABASE: OnceLock<Database> = OnceLock::new();
+
+fn init_database(url: &str) {
+    let _ = DATABASE.set(Database::connect(url));
+}
+```
+
+Do not add `once_cell` for new code. Use the standard library equivalent.

package/src/discovery/builtin-rules/rs-match-ergonomics.md

@@ -0,0 +1,67 @@
+---
+description: Use match ergonomics instead of ref/ref mut patterns
+condition:
+  - "\\(ref mut "
+  - "\\(ref [a-z_]"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use match ergonomics instead of explicit `ref` / `ref mut` patterns. Borrow the scrutinee and let bindings receive references.
+
+## Shared references
+
+```rust
+// Before
+match value {
+    Some(ref item) => println!("{item}"),
+    None => {}
+}
+
+// After
+match &value {
+    Some(item) => println!("{item}"),
+    None => {}
+}
+
+if let Some(item) = &value {
+    println!("{item}");
+}
+```
+
+## Mutable references
+
+```rust
+// Before
+match value {
+    Some(ref mut item) => *item += 1,
+    None => {}
+}
+
+// After
+match &mut value {
+    Some(item) => *item += 1,
+    None => {}
+}
+
+if let Some(item) = &mut value {
+    *item += 1;
+}
+```
+
+## Result
+
+```rust
+// Before
+match result {
+    Ok(ref data) => println!("{data}"),
+    Err(ref err) => eprintln!("{err}"),
+}
+
+// After
+match &result {
+    Ok(data) => println!("{data}"),
+    Err(err) => eprintln!("{err}"),
+}
+```
+
+Modern Rust rarely needs `ref` in patterns. Borrow the value being matched.

package/src/discovery/builtin-rules/rs-parking-lot.md

@@ -0,0 +1,44 @@
+---
+description: Use parking_lot instead of std::sync for Mutex/RwLock
+condition:
+  - "\\.lock\\(\\)\\.unwrap\\(\\)"
+  - "\\.read\\(\\)\\.unwrap\\(\\)"
+  - "\\.write\\(\\)\\.unwrap\\(\\)"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use `parking_lot::{Mutex, RwLock}` instead of `std::sync::{Mutex, RwLock}` when code immediately unwraps lock results.
+
+## Why
+
+- `lock()`, `read()`, and `write()` return guards directly.
+- No poisoning error path to unwrap.
+- Guards are smaller and faster in common contention cases.
+- The call site shows locking, not error handling boilerplate.
+
+## Migration
+
+```rust
+// Before
+use std::sync::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock().unwrap();
+
+// After
+use parking_lot::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock();
+```
+
+## Equivalents
+
+| std::sync | parking_lot |
+| --- | --- |
+| `Mutex<T>` | `Mutex<T>` |
+| `RwLock<T>` | `RwLock<T>` |
+| `Condvar` | `Condvar` |
+| `Once` | `Once` |
+
+## Keep async locks async
+
+Use `tokio::sync::Mutex` / `tokio::sync::RwLock` when a guard is held across `.await` or the lock belongs to async coordination.