Zacaria · Oct 14, 2026 · Oct 13, 2026 · Oct 14, 2026 · Oct 14, 2026
@@ -26,3 +26,7 @@ For product details and MCP behavior, read `README.md`.
 ## 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`.
+
+## Lessons
+
+- 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.
@@ -25,9 +25,10 @@ Thanks for contributing to Kibana Log Investigation MCP.
 
 ## Source Catalogs
 
-- Start from `config/sources.example.json`.
+- 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.
-- `config/sources.runtime.json` is generated by `configure` and is ignored by git.
 
 ## Schema Endpoints
 

@@ -2,7 +2,7 @@
 
 This is the canonical install and handoff guide for `@havesomecode/kibana-mcp-server`.
 
-The supported newcomer path is a prompt-free, connection-only bootstrap. Bootstrap never lists, scans, infers, or configures Kibana indexes. Agents must use the CLI contract below instead of editing Codex or MCP configuration files.
+The supported newcomer path is connection-only bootstrap. It prompts for missing connection values and is prompt-free when all values are supplied. Bootstrap never lists, scans, infers, or configures Kibana indexes. Agents must use the CLI contract below instead of editing Codex or MCP configuration files.
 
 ## Version-Matched README Handoff
 
@@ -32,15 +32,15 @@ Pass the verified URL and resolved commit to the receiving agent. A master previ
 - Node.js 22 or newer
 - `codex` on `PATH` when `--client codex` is used
 - a Kibana base URL reachable with basic authentication
-- credentials supplied through a trusted environment or stdin
+- credentials supplied through a trusted environment, stdin, or a secret prompt
 
-Provision these machine values before installation:
+For prompt-free automation, provision these values before installation:
 
 - `KIBANA_BASE_URL`
 - `KIBANA_USERNAME`
 - `KIBANA_PASSWORD`
 
-No index is required or accepted during bootstrap.
+Without these values, bootstrap prompts for the missing connection inputs. No index is required or accepted during bootstrap.
 
 ## Install The Agent Skill
 
@@ -73,7 +73,7 @@ npx -y @havesomecode/kibana-mcp-server bootstrap \
   --client codex
 ```
 
-Bootstrap is non-interactive and idempotent for profiles it generated. It:
+With all connection values supplied, bootstrap is non-interactive. It is idempotent for profiles it generated and:
 
 1. validates the connection inputs;
 2. checks for a missing or conflicting Codex registration;
@@ -89,6 +89,8 @@ Bootstrap is non-interactive and idempotent for profiles it generated. It:
 
 A non-zero exit means installation did not complete. A successful exit verifies the connection, not any index.
 
+After bootstrap, remove `KIBANA_BASE_URL`, `KIBANA_USERNAME`, and `KIBANA_PASSWORD` from the MCP server environment before reconnecting so startup uses the saved profile. In Bash, run `unset KIBANA_BASE_URL KIBANA_USERNAME KIBANA_PASSWORD`; in PowerShell, run `Remove-Item Env:KIBANA_BASE_URL, Env:KIBANA_USERNAME, Env:KIBANA_PASSWORD -ErrorAction SilentlyContinue`. Leaving direct connection values set overrides profile selection and requires an explicit catalog path or store.
+
 ## Explicit Index Selection
 
 Start a fresh agent session after bootstrap and call `discover`. An empty catalog responds with instructions to ask the user which exact Kibana index or index pattern they want to use.
@@ -104,6 +106,8 @@ The safe sequence is:
 
 `configure_index` accepts no Kibana credentials. A validation failure leaves the existing catalog unchanged.
 
+The MCP server starts only with a configured connection. Bootstrap saves one for subsequent starts. Operators who supply the connection directly through environment variables must also set `KIBANA_SOURCE_CATALOG_PATH`, or declare a catalog store in a configuration file. No catalog is loaded implicitly from the checkout, and no MCP tool accepts connection credentials.
+
 ## Secret Input
 
 Never put a password in a command-line argument. Supported sources, in precedence order:
@@ -155,7 +159,7 @@ If a profile points to a hand-authored or operator-modified catalog, bootstrap f
 
 ## Example Catalog Policy
 
-`config/sources.example.json` is documentation data. It never participates in bootstrap precedence. Guided `setup` remains available for operators who explicitly want a hand-authored catalog:
+`config/sources.example.json` is documentation data. It never participates in bootstrap precedence. `bootstrap` is always connection-only, including without flags. Bare `setup` guides operators who explicitly want a hand-authored catalog; with connection options, `setup` uses the same connection-only bootstrap flow:
 
 ```bash
 npx -y @havesomecode/kibana-mcp-server setup

@@ -24,18 +24,29 @@ The server never writes to Elasticsearch or Kibana, and never guesses an index.
 
 ## Quick start
 
-Pre-provision the connection values in the environment, then bootstrap:
+Bootstrap the connection; missing values are prompted for:
+
+```bash
+npx -y @havesomecode/kibana-mcp-server bootstrap --client codex
+```
+
+For prompt-free automation, provision the connection values in the environment:
 
 ```bash
 export KIBANA_BASE_URL='https://kibana.example.com'
 export KIBANA_USERNAME='elastic'
 export KIBANA_PASSWORD='use-a-secret-provider'
 
 npx -y @havesomecode/kibana-mcp-server bootstrap --client codex
+unset KIBANA_BASE_URL KIBANA_USERNAME KIBANA_PASSWORD
 ```
 
 Bootstrap verifies only the Kibana connection, creates an empty managed catalog, stores the credentials securely and registers the server. It does not list, scan, infer, or configure indexes: the agent asks which exact index or pattern to use, then calls `configure_index`.
 
+Clear the connection variables from the MCP server environment after bootstrap so startup uses the saved profile. Direct environment connections take precedence over profiles and require an explicit catalog path or store.
+
+The server requires a connection at startup. Use bootstrap, a configuration file, or connection environment variables with an explicit `KIBANA_SOURCE_CATALOG_PATH`. It does not accept credentials through MCP tools or search the checkout for a catalog. `bootstrap` always saves only the connection. Bare `setup` guides hand-authored catalog import; `setup` with connection options uses the same bootstrap flow.
+
 Never pass passwords as command-line arguments. Use `KIBANA_PASSWORD`, `--password-env NAME`, or `--password-stdin`.
 
 Install the agent skill that teaches the investigation workflow:

@@ -3,119 +3,28 @@ date: 2026-04-09
 topic: ergonomic-install-and-durable-setup
 ---
 
-# Ergonomic Install and Durable Setup
+# Installation and Durable Setup Requirements
 
-## Problem Frame
+These are the retained product decisions from the original requirements discussion. Completed implementation sequencing, speculative architecture and migration instructions are omitted. The current operator contract is in [INSTALL.md](../../INSTALL.md).
 
-The current setup story is workable for technical operators, but it is still too friction-heavy for non-technical users and for lightweight agent handoff. There is already a good long-form prompt in `INSTALL.md`, but there is not yet a true “copy this and go” machine-install surface for humans, and the normal setup story still leans too much on manual `KIBANA_*` configuration and explicit `configure` behavior.
+## Installation
 
-That friction shows up in two visible ways:
+- Provide copyable human commands and agent instructions, with both published-package and repository-plugin paths. Document actual distribution availability rather than implying an unpublished package is usable.
+- A human can start connection bootstrap without manually exporting variables; prompt only for missing connection values. Fully supplied inputs must support prompt-free automation.
+- Verify the base URL and connection before saving. Bootstrap must not guess, enumerate, scan or select indexes; configure an index only after the operator explicitly names it.
 
-- a user wants a simple install section with something they can copy directly into a shell or paste into an agent
-- a newly opened thread may still require configuration work before the MCP is useful, which undermines the idea of “install once, use everywhere on this machine”
+## Durable Use
 
-The goal is to make the product feel like a normal tool for non-technical users: install it with one command or one agent prompt, answer a short guided setup once, store the right machine-level defaults securely, and have future threads work without repeating setup.
+- Save one machine-level default profile and support additional named environments. Later threads must reuse saved configuration without repeating setup.
+- Explicit connection overrides take precedence over saved profiles. Clear bootstrap-only connection variables before saved-profile startup.
+- Preserve operator-authored catalogs and isolate named environments; replacement requires an explicit operator choice.
 
-## Approach Comparison
+## Credentials and Local State
 
-| Approach | Description | Pros | Cons | Recommendation |
-| --- | --- | --- | --- | --- |
-| Docs-only polish | Add clearer commands and prompts, but keep env vars and repeated configure steps as the main contract | Fastest to ship | Does not solve the new-thread or machine-level durability problem | No |
-| Guided install plus durable machine profile | Offer copyable install surfaces for humans and agents, then launch a first-run setup that stores secrets securely and remembers a default profile for later threads | Solves both install friction and reconfiguration friction | Requires new profile/persistence behavior | Yes |
-| Session-only setup | Launch a guided setup, but do not persist enough state to reuse it later | Lower security/storage complexity | Still forces repeated setup in new threads and new sessions | No |
+- Keep secrets separate from catalog and profile metadata, using the supported platform credential store on macOS, Windows and Linux.
+- Explain unavailable or locked secret stores without silently storing plaintext credentials or making manual secret exports the normal human onboarding flow.
+- Never put passwords in command arguments, client configuration, source catalogs or summaries.
 
-## User Flow
+## Boundaries
 
-```mermaid
-flowchart TB
-    A["User copies install command or agent prompt"] --> B["Tool installs"]
-    B --> C["Guided setup starts immediately"]
-    C --> D["User enters Kibana URL, username, password, default environment"]
-    D --> E["Secrets stored in OS credential store"]
-    E --> F["Machine default profile saved"]
-    F --> G["User can add another environment or finish"]
-    G --> H["Future threads use saved default without reconfigure"]
-```
-
-## Requirements
-
-**Install Surfaces**
-- R1. The product must expose a copyable human install command that a non-technical user can run directly on their machine.
-- R2. The product must expose a copyable agent prompt that a user can paste into Codex or another agent to complete installation and setup.
-- R3. The public install story must support both a clone-free install path and a repo-based fallback path.
-- R4. When clone-free install is not yet available in a given release posture, user-facing docs must say so clearly and present the repo-based fallback immediately below it rather than implying the simpler path already works.
-- R5. The recommended install surface must be the simplest available path, but the fallback path must remain easy to find and copy.
-
-**Guided Setup**
-- R6. A normal supported install must launch guided setup immediately after installation instead of requiring users to manually define `KIBANA_*` variables before first use.
-- R7. Guided setup must ask only for the minimum information needed for a first working connection:
-  - Kibana base URL
-  - username
-  - password
-  - a default environment/profile name
-- R8. Guided setup must validate common input mistakes before saving, including the current known pitfall where a user pastes a full Kibana API endpoint instead of the base URL prefix.
-- R9. Guided setup must offer an “add another environment” continuation after the first successful profile so users can save additional environments without rerunning the full install flow from scratch.
-
-**Durable Machine-Level Use**
-- R10. After first-run setup succeeds, the tool must persist a machine-level default profile so future threads on that machine can use the MCP without rerunning `configure`.
-- R11. A newly opened thread should be able to use the saved default profile automatically unless the user explicitly chooses a different saved environment or the saved configuration is invalid.
-- R12. The default user experience must be “install once, configure once, use across later threads” rather than “configure per thread.”
-- R13. The setup model must support one default environment first, with optional additional named environments such as `prod` or `staging`.
-
-**Secrets and Local State**
-- R14. Secrets must be stored in the platform credential store rather than in normal documentation steps or hand-edited environment variables.
-- R15. The supported secure storage story must cover macOS, Windows, and Linux from the start.
-- R16. Non-secret local state such as saved environment names, source-catalog paths, or profile metadata must be stored separately from secrets.
-- R17. If the platform credential store is unavailable, locked, or unsupported in a specific runtime context, the product must explain that clearly and guide the user to a supported fallback path without telling a non-technical user to export raw env vars manually as the primary flow.
-
-**Cross-Surface Consistency**
-- R18. The guided setup and durable-profile behavior must work for both human-driven installs and agent-driven installs.
-- R19. The product’s public surfaces must consistently explain the install and setup story across `README.md`, `INSTALL.md`, the future Pages site, and plugin/package metadata.
-- R20. The advanced env-var/bootstrap path may remain available for power users and compatibility, but it must no longer be the default onboarding story.
-
-## Success Criteria
-
-- A non-technical user can install the tool by copying either one shell command or one agent prompt.
-- The normal install path reaches a guided setup flow without asking the user to define `KIBANA_*` variables by hand.
-- A user enters connection details once and can open a new thread later without rerunning `configure`.
-- A user can keep one default environment and optionally save additional named environments after the first successful setup.
-- Public install docs clearly distinguish the preferred clone-free path from the repo-based fallback when package distribution status changes.
-
-## Scope Boundaries
-
-- No browser-based Kibana OAuth or SSO flow in this tranche.
-- No requirement to sync saved environments across multiple machines.
-- No replacement of the advanced env-var bootstrap path for power users or automation.
-- No attempt to solve organization-wide fleet management or shared team credential provisioning.
-- No requirement for a full graphical desktop UI; a guided CLI or agent-driven flow is sufficient if it is ergonomic for non-technical users.
-
-## Key Decisions
-
-- **Two first-class install surfaces:** The product should support both a human copy-paste install command and a copy-paste agent prompt.
-- **Guided setup starts immediately after install:** The first-run flow should ask for only the minimum connection details and should not expect manual env-var editing.
-- **Machine-level persistence is the default behavior:** New threads should inherit a saved default profile instead of requiring `configure` again.
-- **One default profile first, more environments optionally:** The primary path stays simple for non-technical users, with multi-environment support exposed as a follow-up choice rather than as an upfront burden.
-- **OS credential storage is the default secrets posture:** Secrets should live in the operating system credential store rather than in the normal install instructions or plain local config.
-- **Env vars become an advanced compatibility path, not the main onboarding contract:** Keep them for power users, but do not force them into the normal first-run experience.
-
-## Dependencies / Assumptions
-
-- The tool will need a stable machine-local place to store non-secret profile metadata.
-- The installation/runtime surfaces will need a way to resolve a saved default profile before requiring manual runtime `configure`.
-- Public package distribution may still arrive later than the repo-based fallback, so install surfaces must handle staged availability cleanly.
-
-## Outstanding Questions
-
-### Resolve Before Planning
-- None.
-
-### Deferred to Planning
-- [Affects R3-R5][Technical] What staged rollout shape best supports both clone-free install and repo-based fallback while the public package path is still gated?
-- [Affects R10-R17][Technical] What machine-local profile format and lookup order should the runtime use so saved defaults work across new threads without breaking existing repo-local flows?
-- [Affects R14-R17][Needs research] What is the most reliable cross-platform credential-store integration strategy for macOS, Windows, and Linux, and what fallback behavior is acceptable when Linux secret-store support is absent or locked?
-- [Affects R6-R13][Technical] Should guided setup live in the CLI/runtime surface, in the plugin install flow, or in a shared setup command used by both?
-- [Affects R18-R20][Technical] How should existing env-var-based users migrate to durable machine profiles without breaking current workflows?
-
-## Next Steps
-
-→ /prompts:ce-plan for structured implementation planning
+Human and agent installation must use the same setup behavior. OAuth/SSO, machine-to-machine profile synchronization, fleet management and a graphical setup application are outside this scope. Preserve advanced automation options without retaining a second argument parser or owner-only migration machinery.