From 5311f0b98abb9d0ec7d19a1e769a85bc883d5d00 Mon Sep 17 00:00:00 2001 From: Adil Karim Date: Wed, 4 Nov 2026 06:07:26 +0000 Subject: [PATCH] fix(onboarding): document keyless SSH guide fetches (OPE-94) Use explicit keyboard-interactive-compatible options for agent guide fetches, explain OpenSSH option precedence, and preserve host-key and identity-key checks. Amp-Thread-ID: https://ampcode.com/threads/T-b58ef7fb-f69f-471f-8a0c-02453b35793c Co-authored-by: Amp --- assets/skills/agents.md | 11 ++++++++++- assets/skills/openlore/SKILL.md | 9 +++++++++ assets/skills/setup.md | 12 ++++++++++-- assets/skills/teach.md | 24 ++++++++++++++++-------- docs/how-to/usage.md | 15 +++++++++++++++ internal/skills/skills_test.go | 2 +- pkg/openlore/skill_examples_test.go | 2 +- 7 files changed, 62 insertions(+), 13 deletions(-) diff --git a/assets/skills/agents.md b/assets/skills/agents.md index 52225ca..4cf26be 100644 --- a/assets/skills/agents.md +++ b/assets/skills/agents.md @@ -17,7 +17,7 @@ it runs touches the local host. Search it before guessing: decisions, or shared team knowledge — search the knowledge repository before guessing or asking. If an `openlore` skill is installed in this harness, load it for the full procedures; this section is the summary. To install the -skill: `ssh {{ ssh_target }} openlore-skill > /openlore/SKILL.md`. +skill: `ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes {{ ssh_target }} openlore-skill /openlore/SKILL.md`. If Claude Code's permission system denies a call to the `openlore` MCP tool, it has mistaken an OpenLore command for an operation on the local filesystem. @@ -32,6 +32,15 @@ Use this when the `openlore` MCP server is not connected. ssh {{ ssh_target }} ``` +For keyless one-shot commands, use +`ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes {{ ssh_target }} ''`. +Keyless OpenLore uses keyboard-interactive authentication with zero prompts; +`BatchMode=yes` disables it. Do not prepend `-o BatchMode=yes`: OpenSSH uses +the first value for each option. For guide fetches and reads, add `` for an identity - Main paths: {{if .Mounts}}{{range $i, $m := .Mounts}}{{if $i}}, {{end}}`{{$m}}`{{end}} (run `lore docsets` for access levels){{else}}``{{end}} +For keyless access, add `-o BatchMode=no -o KbdInteractiveAuthentication=yes` +before the SSH target in the commands below. Do not prepend `-o BatchMode=yes`: +OpenSSH uses the first value for each option, and batch mode disables the +zero-prompt keyboard-interactive authentication that keyless OpenLore uses. +For reads and guide fetches, add `` to add people/folders; deployment is -similarly “run deploy” or `ssh openlore.sh deploy | `, and its +`ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh onboarding ` to add people/folders; deployment is +similarly “run deploy” or `ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh deploy `, and its benefit is to share the server with the team. Explain that setup is complete and onboarding is optional customization. One project is one authoritative server; do not create staging environments. +For these guide fetches, keep the explicit SSH options and do not prepend +`-o BatchMode=yes`: OpenSSH uses the first value for each option. Keyless +OpenLore uses keyboard-interactive authentication with zero prompts, which +`BatchMode=yes` disables. Redirecting stdin from `/dev/null` keeps the fetch +non-interactive. Keep host-key verification enabled; ask the person to verify +an unknown host instead of disabling the check. Do not change the authenticated +local verification commands above or remove their identity keys. + If the person stops here, open the finished setup record for them and say so: ```bash diff --git a/assets/skills/teach.md b/assets/skills/teach.md index f9cdfcd..8b3632b 100644 --- a/assets/skills/teach.md +++ b/assets/skills/teach.md @@ -49,7 +49,7 @@ Then ask the initial question again (options A and B). Default port: 2222 (openlore.sh uses 22). 2. Verify the connection: ```shell - ssh {{ ssh_target }} + ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes {{ ssh_target }} skills # list every guide the server carries -ssh
# fetch one, e.g. passkeys, upgrade, deploy-fly +ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes
skills -lore", - "ssh openlore.sh setup", + "ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh setup -lore", diff --git a/pkg/openlore/skill_examples_test.go b/pkg/openlore/skill_examples_test.go index e6ba77c..4ad9720 100644 --- a/pkg/openlore/skill_examples_test.go +++ b/pkg/openlore/skill_examples_test.go @@ -209,7 +209,7 @@ func TestSkillDocumentsRenderAgainstRealMounts(t *testing.T) { t.Errorf("%s for %s mentions a folder this server does not have:\n%s", command, who, doc) } if command == "teach" { - if !strings.Contains(doc, "ssh -p 2299 localhost\n") { + if !strings.Contains(doc, "ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes -p 2299 localhost