Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion assets/skills/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 > <skills-dir>/openlore/SKILL.md`.
skill: `ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes {{ ssh_target }} openlore-skill </dev/null > <skills-dir>/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.
Expand All @@ -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 }} '<command>'`.
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 `</dev/null`
to avoid consuming local stdin; do not add it when piping content to a write.
Keep host-key verification enabled and ask the person to verify an unknown
host. Servers that require an identity key still require that key.

Each `ssh` invocation is an independent session, so use absolute paths.
{{if .Mounts}}
### Layout
Expand Down
9 changes: 9 additions & 0 deletions assets/skills/openlore/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,15 @@ independent session, so use absolute paths.
- Key: none (keyless) — or `-i <path-to-key>` for an identity
- Main paths: {{if .Mounts}}{{range $i, $m := .Mounts}}{{if $i}}, {{end}}`{{$m}}`{{end}} (run `lore docsets` for access levels){{else}}`<run 'tree -L 2 /' once and record the layout here>`{{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 `</dev/null` to avoid consuming local stdin;
leave stdin connected when piping content to a write. Keep host-key verification
enabled and ask the person to verify an unknown host. These options do not
replace an identity key on servers that require one.

## Reading and searching

```shell
Expand Down
12 changes: 10 additions & 2 deletions assets/skills/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -513,12 +513,20 @@ ssh -F .local/ssh_config lore-local 'cat /channel/infrastructure/openlore-server
Offer an initial commit only after explicit approval; never push automatically.

Then ask whether to continue in this session (“run onboarding”) or later with
`ssh openlore.sh onboarding | <agent-cli>` to add people/folders; deployment is
similarly “run deploy” or `ssh openlore.sh deploy | <agent-cli>`, and its
`ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh onboarding </dev/null | <agent-cli>` to add people/folders; deployment is
similarly “run deploy” or `ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh deploy </dev/null | <agent-cli>`, 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
Expand Down
24 changes: 16 additions & 8 deletions assets/skills/teach.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 }} </dev/null
```
3. Show them how to explore:
```shell
Expand All @@ -62,8 +62,8 @@ Then ask the initial question again (options A and B).
4. Offer to onboard their agents. The server carries its own instructions —
fetch and follow them:
```shell
ssh {{ ssh_target }} openlore-skill # portable Agent Skills file
ssh {{ ssh_target }} agents # AGENTS.md snippet
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes {{ ssh_target }} openlore-skill </dev/null # portable Agent Skills file
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes {{ ssh_target }} agents </dev/null # AGENTS.md snippet
```
5. Finish with a short ✅ plain-language summary of what now works.

Expand All @@ -80,15 +80,23 @@ the folder or hand-write `openlore.yml` here; let `setup` collect the answers
and run init once. Fetch it and follow it now:

```shell
ssh openlore.sh setup
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh setup </dev/null
```

Use these SSH options exactly for guide fetches; do not prepend
`-o BatchMode=yes`. OpenSSH uses the first value for each option. A keyless
OpenLore connection uses keyboard-interactive authentication with zero prompts,
which `BatchMode=yes` disables. `</dev/null` keeps the fetch non-interactive.
Keep normal host-key verification; if it requires confirmation, ask the person
to verify the host instead of disabling the check. These options do not bypass
authentication on servers that require an identity key.

Then stop here — the `setup` skill takes over. After it, `onboarding` adds
identities and `deploy` shares the server with the team:

```shell
ssh openlore.sh onboarding
ssh openlore.sh deploy
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh onboarding </dev/null
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh deploy </dev/null
```

## Going further
Expand All @@ -97,8 +105,8 @@ Every guide ships on the server itself. Fetch what the moment needs instead of
keeping it all in context:

```shell
ssh <address> skills # list every guide the server carries
ssh <address> <name> # fetch one, e.g. passkeys, upgrade, deploy-fly
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes <address> skills </dev/null # list every guide the server carries
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes <address> <name> </dev/null # fetch one, e.g. passkeys, upgrade, deploy-fly
```

## Wrap up
Expand Down
15 changes: 15 additions & 0 deletions docs/how-to/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,21 @@ deployment; you do not need to choose a transport or hand-write `openlore.yml`
first. If you use another coding agent, give it the output of
`ssh openlore.sh setup` instead.

When an agent fetches the guide on a machine without SSH keys, use:

```shell
ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh setup </dev/null
```

Keyless OpenLore uses keyboard-interactive authentication with zero prompts.
`BatchMode=yes` disables that method, so an agent that adds it gets
`Permission denied (publickey,keyboard-interactive)`. Do not prepend a conflicting
`-o BatchMode=yes`: OpenSSH uses the first value for each option. Redirecting
stdin from `/dev/null` keeps the fetch non-interactive. Keep host-key verification
enabled and verify an unknown host before retrying. The same options work for
`teach`, `onboarding`, `deploy`, and the other instruction commands; servers
that require an identity key still require it.

The generated repository tracks `openlore.yml`, a thin `Containerfile` based on
a stable OpenLore release, and provider artifacts under `deploy/`. Initial
policy and filesystem state live in gitignored `.local/` until the first
Expand Down
2 changes: 1 addition & 1 deletion internal/skills/skills_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ func TestEmbeddedDeploymentSkills(t *testing.T) {
expected := map[string][]string{
"teach": {
"lore init <team-slug>-lore",
"ssh openlore.sh setup",
"ssh -o BatchMode=no -o KbdInteractiveAuthentication=yes openlore.sh setup </dev/null",
},
"setup": {
"<team-slug>-lore",
Expand Down
2 changes: 1 addition & 1 deletion pkg/openlore/skill_examples_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 </dev/null\n") {
t.Errorf("teach does not render the ssh target into its examples:\n%s", doc)
}
return
Expand Down
Loading