@simonsbs/keylore 1.0.0-rc5 → 1.0.0

package/README.md

@@ -6,7 +6,7 @@ The design goal comes directly from the local `KeyLore.md` production spec used
 
 ## Status
 
-This repository is incubating privately today, but it is structured to be published as open source without a cleanup pass. The repo already includes:
+This repository is now public and open source. The repo already includes:
 
 - an Apache-2.0 project license and `NOTICE`
 - contributor and security policies
@@ -64,13 +64,14 @@ This repository is incubating privately today, but it is structured to be publis
 
 ## What is intentionally deferred
 
-The full `KeyLore.md` specification is broader than a sane `v1.0.0-rc5` delivery. The main remaining work before `v1.0.0` is:
+The full `KeyLore.md` specification is broader than a sane `v1.0.0` delivery. The main remaining work after `v1.0.0` is:
 
-- public release polish and final operator documentation cleanup
+- continued UX refinement for context authoring
+- stronger self-hosted production guidance for advanced deployments
 
 Those items are tracked in [docs/roadmap.md](/home/simon/keylore/docs/roadmap.md) and mapped back to the spec in [docs/keylore-spec-map.md](/home/simon/keylore/docs/keylore-spec-map.md).
 
-The active post-`v1.0.0-rc5` refocus is documented in [docs/core-mode-plan.md](/home/simon/keylore/docs/core-mode-plan.md): make the default user journey "add secret, add context, connect MCP, use it" and push broader operator features behind an advanced path.
+The active post-`v1.0.0` refocus is documented in [docs/core-mode-plan.md](/home/simon/keylore/docs/core-mode-plan.md): keep the default user journey "add secret, add context, connect MCP, use it" simple and push broader operator features behind an advanced path.
 
 The handoff from local core mode to advanced self-hosted mode is documented in [docs/production-handoff.md](/home/simon/keylore/docs/production-handoff.md).
 
@@ -93,7 +94,7 @@ That starts KeyLore in the background. Use `keylore-http status`, `keylore-http
 For a clean Linux VM install from npm instead of cloning the repo:
 
 ```bash
-npm install -g @simonsbs/keylore@next
+npm install -g @simonsbs/keylore
 keylore-http start
 ```
 
@@ -118,28 +119,38 @@ KeyLore now redirects `/` to `/admin` and automatically opens a local operator s
 
 If that local session bootstrap fails for any reason, use `Start working locally` or the manual sign-in form shown on the page.
 
-4. In `Save token`, choose the closest template for the token you are adding, such as `GitHub read-only`, `GitHub write-capable`, `npm read-only`, or `Internal service token`, then fill in:
+4. In `Quick start`, follow the short path: add token, test token, then connect your AI tool.
+
+5. In `Your tokens`, click `Add token`, then fill in:
 - `Name shown in KeyLore`
 - `Token key`
+- `Where to store the token`
+- `Service name`
 - `Paste token`
 - `Where can it be used?`
+- `Explain this token for people`
 - `Tell the AI when to use this token`
 
-That stores the raw token outside the searchable catalogue and keeps only the LLM-facing metadata in the credential record.
+That stores the raw token outside the searchable catalogue and keeps only the metadata record in the credential catalogue.
 
-5. Review `Writing help` and `What the AI will see` in the form to confirm the agent-facing record is specific, useful, and secret-free. `Token key` is the unique identifier for the token; if KeyLore says a token already exists, change that field and save again. Open `Advanced token settings` only if you need to change storage mode, risk level, service name, tags, or write access.
+6. Use the inline `(i)` help beside each field and review `What the AI will see` to confirm the record is specific, useful, and secret-free. `LLM context` is the primary retrieval hint for agents. `User context` explains the human purpose of the token. `Token key` is the unique identifier for the token; if KeyLore says a token already exists, change that field and save again.
 
-6. In `Saved tokens`, look under `Your tokens` for the ones you added yourself. `Included examples` are seeded local records and are shown separately so they do not get confused with your own tokens.
+7. In `Saved tokens`, everything is now listed together in one place. Example records are marked as examples, and they can be edited or deleted from the same list.
 
-7. In `Test credential`, choose `Token to check`, set the `URL to call with this token`, and run the check.
+8. In `Test credential`, choose `Token to check`, set the `URL to call with this token`, and run the check.
 
 The check makes a real brokered `http.get` call with that token and URL. Success means the token, the target domain, and KeyLore policy all allowed the request.
 
-8. In `Connect your AI tool`, copy the generated Codex or Gemini CLI local snippet for the easiest setup. Use the built-in `First prompt to try` examples after you restart the client. If you want remote HTTP MCP instead, open `Remote or advanced connection options` and mint an `/mcp` token there.
+9. In `Connect your AI tool`, pick the tool tab you want:
+- `Codex`: copy the snippet or click `Apply to my Codex settings` to merge it into `~/.codex/config.toml`, then restart Codex
+- `Gemini CLI`: copy the snippet or click `Apply to my Gemini settings` to merge it into `~/.gemini/settings.json`, then restart Gemini
+- `Claude CLI`: copy the command or click `Apply to my Claude settings` to register KeyLore, then restart Claude
+
+Use the built-in `First prompt to try` example after restarting the client. If you want remote HTTP MCP instead, open `Remote or advanced connection options` and mint an `/mcp` token there.
 
 Everything beyond that now sits behind `Show advanced controls` in the UI, so a first-run user can ignore tenants, OAuth client administration, approvals, backups, audit, and system internals entirely.
 
-After creation, use `Inspect or edit AI-facing context` inside `Save token` if you need to refine the metadata without re-entering or exposing the stored secret. Saved token cards also support lightweight lifecycle actions such as rename, retag, and archive/restore under `More actions`.
+After creation, use `Edit token` from the saved-token list if you need to refine the metadata or replace the stored value for a locally stored token. Token creation and editing both happen in a popup now, while the main page stays focused on the token list, testing, and MCP connection.
 
 When that local path stops being enough, use [docs/production-handoff.md](/home/simon/keylore/docs/production-handoff.md) to decide when to switch to external secret backends, real OAuth clients, approvals, and tenant-separated self-hosting.
 
@@ -226,7 +237,7 @@ Validate the Helm deployment path:
 npm run ops:helm-validate
 ```
 
-Run the release candidate gates:
+Run the release gates:
 
 ```bash
 npm run ops:release-verify

package/data/catalog.json

@@ -13,6 +13,8 @@
       "expiresAt": null,
       "rotationPolicy": "Rotate every 90 days",
       "lastValidatedAt": "2026-03-13T00:00:00.000Z",
+      "userContext": "Shared example credential for GitHub metadata lookups in local demos. Keep it read-only and prefer a real user-owned token when one exists.",
+      "llmContext": "Fallback GitHub read-only demo credential. Use for repository metadata, issue lookup, release inspection, and rate-limit reads only when no better user-owned GitHub token is available. Never use for write operations.",
       "selectionNotes": "Use for repository metadata, issue lookup, and release inspection. Never use for write operations.",
       "binding": {
         "adapter": "env",
@@ -37,6 +39,8 @@
       "expiresAt": null,
       "rotationPolicy": "Rotate every 90 days",
       "lastValidatedAt": "2026-03-13T00:00:00.000Z",
+      "userContext": "Shared example credential for npm package metadata inspection in local demos. Keep it read-only and do not use it for publish workflows.",
+      "llmContext": "Fallback npm read-only demo credential. Use for package metadata inspection, dependency lookup, and registry read operations only. Never use for publish or package mutation workflows.",
       "selectionNotes": "Use for package metadata inspection only. Publishing is intentionally excluded from the default demo policy.",
       "binding": {
         "adapter": "env",

package/dist/config.js

@@ -205,7 +205,7 @@ export function loadConfig(cwd = process.cwd()) {
     }
     return {
         appName: "keylore",
-        version: "1.0.0-rc5",
+        version: "1.0.0",
         dataDir,
         bootstrapCatalogPath: path.resolve(runtimeRoot, "data", env.KEYLORE_CATALOG_FILE ?? "catalog.json"),
         bootstrapPolicyPath: path.resolve(runtimeRoot, "data", env.KEYLORE_POLICY_FILE ?? "policies.json"),

package/dist/domain/types.js

@@ -113,6 +113,8 @@ export const credentialRecordSchema = z.object({
     rotationPolicy: z.string().min(1),
     lastValidatedAt: z.string().datetime().nullable(),
     selectionNotes: z.string().min(1),
+    userContext: z.string().min(1).optional(),
+    llmContext: z.string().min(1).optional(),
     binding: credentialBindingSchema,
     tags: z.array(z.string().min(1)).default([]),
     status: credentialStatusSchema.default("active"),
@@ -210,6 +212,52 @@ export const catalogSearchInputSchema = z.object({
 export const createCredentialInputSchema = credentialRecordSchema;
 const secretLikeSelectionNotesPattern = /(gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|sk-[A-Za-z0-9_-]+|AKIA[0-9A-Z]{16})/;
 const vagueSelectionNotesPattern = /^(use when needed|general use|general purpose|for api|api token|token for api|default token|main token)$/i;
+function normalizedLlmContext(value) {
+    return (value.llmContext ?? value.selectionNotes ?? "").trim();
+}
+function normalizedUserContext(value) {
+    return (value.userContext ?? normalizedLlmContext(value)).trim();
+}
+function validateLlmContext(llmContext, ctx, path) {
+    if (!llmContext) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "LLM context is required. Explain when the agent should use this credential.",
+        });
+        return;
+    }
+    if (llmContext.length < 16) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "LLM context must explain when the agent should use this credential in more detail.",
+        });
+    }
+    if (vagueSelectionNotesPattern.test(llmContext)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "LLM context is too vague. Describe the target service, intended use, and what the agent should avoid.",
+        });
+    }
+    if (secretLikeSelectionNotesPattern.test(llmContext)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "LLM context must not contain token-like secret material.",
+        });
+    }
+}
+function validateUserContext(userContext, ctx, path) {
+    if (!userContext) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path,
+            message: "User context is required. Describe the human purpose of this credential.",
+        });
+    }
+}
 export const coreCredentialCreateInputSchema = z
     .object({
     credentialId: z.string().min(1),
@@ -221,7 +269,9 @@ export const coreCredentialCreateInputSchema = z
     sensitivity: sensitivitySchema.default("high"),
     allowedDomains: z.array(z.string().min(1)).min(1),
     permittedOperations: z.array(operationSchema).min(1).default(["http.get"]),
-    selectionNotes: z.string().min(1),
+    selectionNotes: z.string().min(1).optional(),
+    userContext: z.string().min(1).optional(),
+    llmContext: z.string().min(1).optional(),
     rotationPolicy: z.string().default("Managed locally"),
     tags: z.array(z.string().min(1)).default([]),
     status: credentialStatusSchema.default("active"),
@@ -251,28 +301,8 @@ export const coreCredentialCreateInputSchema = z
             message: "Bearer credentials should include a non-empty header prefix.",
         });
     }
-    const selectionNotes = value.selectionNotes.trim();
-    if (selectionNotes.length < 16) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["selectionNotes"],
-            message: "Selection notes must explain when the agent should use this credential in more detail.",
-        });
-    }
-    if (vagueSelectionNotesPattern.test(selectionNotes)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["selectionNotes"],
-            message: "Selection notes are too vague. Describe the target service, intended use, and what the agent should avoid.",
-        });
-    }
-    if (secretLikeSelectionNotesPattern.test(selectionNotes)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["selectionNotes"],
-            message: "Selection notes must not contain token-like secret material.",
-        });
-    }
+    validateLlmContext(normalizedLlmContext(value), ctx, ["llmContext"]);
+    validateUserContext(normalizedUserContext(value), ctx, ["userContext"]);
     if (value.permittedOperations.includes("http.post") && value.scopeTier === "read_only") {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -293,6 +323,8 @@ export const coreCredentialContextUpdateInputSchema = z
     allowedDomains: z.array(z.string().min(1)).min(1).optional(),
     permittedOperations: z.array(operationSchema).min(1).optional(),
     selectionNotes: z.string().min(1).optional(),
+    userContext: z.string().min(1).optional(),
+    llmContext: z.string().min(1).optional(),
     tags: z.array(z.string().min(1)).optional(),
     status: credentialStatusSchema.optional(),
 })
@@ -300,29 +332,11 @@ export const coreCredentialContextUpdateInputSchema = z
     message: "At least one context field must be provided.",
 })
     .superRefine((value, ctx) => {
-    if (value.selectionNotes !== undefined) {
-        const selectionNotes = value.selectionNotes.trim();
-        if (selectionNotes.length < 16) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["selectionNotes"],
-                message: "Selection notes must explain when the agent should use this credential in more detail.",
-            });
-        }
-        if (vagueSelectionNotesPattern.test(selectionNotes)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["selectionNotes"],
-                message: "Selection notes are too vague. Describe the target service, intended use, and what the agent should avoid.",
-            });
-        }
-        if (secretLikeSelectionNotesPattern.test(selectionNotes)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["selectionNotes"],
-                message: "Selection notes must not contain token-like secret material.",
-            });
-        }
+    if (value.selectionNotes !== undefined ||
+        value.llmContext !== undefined ||
+        value.userContext !== undefined) {
+        validateLlmContext(normalizedLlmContext(value), ctx, ["llmContext"]);
+        validateUserContext(normalizedUserContext(value), ctx, ["userContext"]);
     }
     const scopeTier = value.scopeTier;
     const permittedOperations = value.permittedOperations;