docs: make skills and instructions action-first

AGENTS.md

@@ -1,32 +1,31 @@
 # Agent Instructions
 
-## First Step
-
 Read [`INSTALL.md`](./INSTALL.md) first.
 
-If the goal is to set up or use this repository in Codex, treat `INSTALL.md` as the primary operator and handoff guide.
-
-## Setup Priority
+It is the Codex setup and handoff guide.
 
-When working from a fresh clone:
+## Set up a cloned checkout
 
-1. Read `INSTALL.md`
-2. Follow the Codex/plugin installation flow there
-3. Use the plugin-local skills when relevant:
+1. Follow the Codex/plugin flow in `INSTALL.md`.
+2. Use the relevant local skill:
    - `plugins/kibana-log-investigation/skills/ensure-node-runtime/SKILL.md`
    - `plugins/kibana-log-investigation/skills/install-and-configure/SKILL.md`
 
-## Repository Context
+## Before editing
 
-This repo provides a read-only Kibana log investigation MCP server plus a repo-scoped Codex plugin for local installation from a cloned checkout.
-Documented learnings live in `docs/solutions/`, organized by category with YAML frontmatter such as `module`, `tags`, and `problem_type`, and are relevant when working in already documented areas.
+This repo provides a read-only Kibana MCP server and a repo-local Codex plugin.
 
-For product details and MCP behavior, read `README.md`.
+Read `README.md` for product behavior. Check relevant learnings in `docs/solutions/`, organized by category and frontmatter (`module`, `tags`, `problem_type`).
 
 ## CLI conventions
 
-Keep the human CLI decomposed by concern: the executable lives in `src/bin/`, Commander command registration lives in `src/commands/`, and terminal I/O plus Clack prompt adapters live outside command modules. Commands contain only command-specific validation and orchestration; do not add command logic back to `src/cli.ts`.
+- `src/bin/`: executables.
+- `src/commands/`: Commander registration, command-specific validation and orchestration only.
+- Keep terminal I/O and Clack prompt adapters outside command modules.
+
+Do not add command logic back to `src/cli.ts`.
 
 ## Lessons
 
+- When writing skills or instructions, lead with the action, use short numbered steps, keep warnings beside the affected action, and remove repeated rationale without removing contracts.
 - When a project format was used only by the owner, remove its obsolete code, callers, tests and documentation instead of adding compatibility or migration paths.

CONTRIBUTING.md

@@ -1,7 +1,5 @@
 # Contributing
 
-Thanks for contributing to Kibana Log Investigation MCP.
-
 ## Quick Start
 
 1. Ensure Node.js 22+ (see `.node-version`).
@@ -25,25 +23,20 @@ Thanks for contributing to Kibana Log Investigation MCP.
 
 ## Source Catalogs
 
-- Connection bootstrap saves an empty managed catalog with the machine profile; `configure_index` adds only indexes explicitly approved by the user.
-- Guided `setup` imports a hand-authored catalog selected by the operator. Use `config/sources.example.json` only as an explicitly chosen template.
-- Environment-based startup requires `KIBANA_SOURCE_CATALOG_PATH` unless a configuration-file store supplies the catalog. Saved profiles carry their own catalog path; no checkout file is loaded implicitly.
-- Do not commit real environment source catalogs or credentials.
-
-## Schema Endpoints
+1. Use connection bootstrap for an empty managed catalog saved with the machine profile. Add indexes through `configure_index` only with explicit user approval.
+2. Use guided `setup` to import an operator-selected hand-authored catalog. Choose `config/sources.example.json` explicitly if needed as a template.
+3. Set `KIBANA_SOURCE_CATALOG_PATH` for environment startup unless a configuration-file store supplies it. Saved profiles carry their catalog path; no checkout file loads implicitly.
 
-Some Kibana deployments block schema metadata endpoints. When that happens:
+Never commit real environment catalogs or credentials.
 
-- `describe_fields` can return errors
-- exact-field promotion and nested validation may be unavailable
+## Schema Endpoints
 
-Please include this detail in bug reports when relevant.
+Report blocked schema endpoints when relevant: `describe_fields` can fail, and exact-field promotion or nested validation may be unavailable.
 
 ## Pull Requests
 
-- Keep changes focused.
-- Update docs when behavior changes.
-- Ensure `npm run verify` passes before requesting review.
+1. Keep changes focused; update docs when behavior changes.
+2. Pass `npm run verify` before requesting review.
 
 ## Security
 

HANDOFF_timeout-config-bug.md

@@ -1,14 +1,13 @@
 # Handoff: Kibana MCP startup failure on KIBANA_TIMEOUT_MS
 
-## Context
-The Codex MCP entries in `~/.codex/config.toml` were failing to start the Kibana MCP server when `KIBANA_TIMEOUT_MS` was present.
+## Recorded issue — 2026-04-09
 
-As a quick workaround, the `KIBANA_TIMEOUT_MS` lines were removed from the local Codex config entries on 2026-04-09.
+Codex MCP entries in `~/.codex/config.toml` failed to start with `KIBANA_TIMEOUT_MS`. The local workaround removed those lines on 2026-04-09; this is historical evidence, not a current startup check.
 
 ## Reproduction
 The environment values below are intentionally synthetic and portable.
 
-This fails:
+Recorded failing command:
 
 ```bash
 KIBANA_BASE_URL='https://kibana.example.com/logs' \
@@ -24,7 +23,7 @@ ZodError: Invalid input: expected string, received number
 path: ["KIBANA_TIMEOUT_MS"]
 ```
 
-This succeeds:
+Recorded successful command:
 
 ```bash
 KIBANA_BASE_URL='https://kibana.example.com/logs' \
@@ -33,20 +32,18 @@ node dist/src/index.js
 ```
 
 ## Root cause
-`loadConfigFromEnvironment()` parses env with `envSchema.parse(envInput)`, where `KIBANA_TIMEOUT_MS` is transformed from string to number.
-
-Later, after loading the source catalog, it calls `parseAppConfig(env, sourceCatalog)`. But `parseAppConfig()` parses the env again using the same schema, which still expects `KIBANA_TIMEOUT_MS` to be a string input.
-
-That second parse crashes because the already-normalized value is now a number.
+1. `loadConfigFromEnvironment()` calls `envSchema.parse(envInput)`, converting `KIBANA_TIMEOUT_MS` from string to number.
+2. After catalog loading, `parseAppConfig(env, sourceCatalog)` parses that env with the same schema.
+3. The second parse expects a string and crashes on the normalized number.
 
 ## Relevant files
 - `src/config.ts`
 - `dist/src/config.js`
 - optional tests covering `loadConfigFromEnvironment()` with and without `KIBANA_TIMEOUT_MS`
 
-## Requested follow-up
-Implement a real fix so startup works when `KIBANA_TIMEOUT_MS` is set, then commit and push the change.
+## Original requested follow-up
+
+1. Fix startup with `KIBANA_TIMEOUT_MS`; keep the fix minimal and add focused tests. Do not revert unrelated untracked dirs such as `.codex/` or `openspec/`.
+2. Commit and push the fix.
 
-Constraints:
-- Do not revert unrelated untracked dirs like `.codex/` or `openspec/`.
-- Keep the fix minimal and add focused tests.
+This records the original request; it does not authorize changes or publishing in later documentation tasks.