Context
I read the README as a first-time user after trying runseal in a repo with profile-local wrappers and resources. The core model is strong, but the README currently feels more like a compact capability spec than an onboarding path.
This is different from #21, which is about no-profile help/error UX. This issue is about README narrative, examples, and first-contact comprehension.
What worked well
The README accurately documents the core concepts:
- profile discovery
- env / symlink / argv injections
resource://... resolution:<name> wrapper routing@profile, @resources, @resolve, @wrappers, @which
The internal command section is especially useful because it shows runseal is not a black-box wrapper: users can inspect profile, resource, and wrapper resolution.
What felt rough
1. The opening is technically accurate but undersells the use case
Current opening:
Run a command inside a small, explicit profile.
This is accurate, but it may not immediately catch users who are dealing with the real problem runseal solves: repo-local execution with private resources and explicit wrappers.
A slightly more use-case-oriented sentence could help, for example:
Use runseal when a repository needs explicit local resources, named wrappers, and env/argv/symlink setup without becoming a task runner or secret manager.
That framing makes it easier to distinguish runseal from Makefile/just/direnv/dotenv.
2. The first example appears to have a bash invocation issue
README currently shows:
runseal --profile ./runseal.toml bash -- -lc 'echo "$RUNSEAL_PROFILE_PATH"'
With bash, -- ends option parsing, so -lc is treated as a positional argument rather than an option. I think the intended example is:
runseal --profile ./runseal.toml bash -lc 'echo "$RUNSEAL_PROFILE_PATH"'
3. The strongest trust-building commands come too late
For a new user, these are very persuasive:
runseal @profile
runseal @resources
runseal @resolve resource://ssh/config
runseal @wrappers
runseal @which :ssh-run
They answer the immediate questions:
- Which profile did runseal select?
- Where is the resource root?
- What does this
resource:// path become?
- Which wrappers are visible?
- Which file will
:name execute?
I would consider moving a short "inspect what runseal sees" block much earlier, before the full profile reference.
4. A 30-second repo-local example would help
The current profile example is comprehensive, but it mixes env, env ops, symlink, argv, and resources at once. A smaller first example may help users see the niche faster:
[resources]
root = ".local"
[[injections]]
type = "env"
[injections.vars]
APP_SSH_CONFIG = "resource://ssh/config"
APP_SECRET_DIR = "resource://secrets"
Then:
runseal @profile
runseal @resolve resource://ssh/config
runseal :ssh host
This shows the key idea: the repo declares a private resource root, runseal resolves it, and wrappers/scripts consume absolute paths instead of guessing repo-relative locations.
5. A sharper "fit / not fit" section would protect the tool's scope
The README already implies restraint, but an explicit section could help avoid mispositioning:
Fits well:
- repo-local private resources
- explicit one-command execution environments
- named wrappers with discoverability
- passing profile-scoped paths to tools like
ssh, kubectl, uv, terraform, etc.
Not trying to be:
- a task dependency graph
- a secret lifecycle manager
- a deployment orchestrator
- a shell auto-activation tool like
direnv
That would make the design restraint more visible.
Suggested structure
One possible README flow:
- What problem runseal solves
- 30-second example
- Inspect what runseal sees (
@profile, @wrappers, @resolve)
- Command routing: external /
: wrapper / @ internal
- Profile capabilities: env / symlink / argv / resources
- Fit / not fit
- Install
- Reference details
Why this matters
The current README gives enough technical facts to use runseal, but the first-contact path requires the reader to already understand the niche. A small narrative pass could help the right users recognize the tool quickly: people with repos full of .local, .env, kubeconfig/SSH config paths, wrapper scripts, and README instructions like "export these variables before running deploy".
Context
I read the README as a first-time user after trying
runsealin a repo with profile-local wrappers and resources. The core model is strong, but the README currently feels more like a compact capability spec than an onboarding path.This is different from #21, which is about no-profile help/error UX. This issue is about README narrative, examples, and first-contact comprehension.
What worked well
The README accurately documents the core concepts:
resource://...resolution:<name>wrapper routing@profile,@resources,@resolve,@wrappers,@whichThe internal command section is especially useful because it shows runseal is not a black-box wrapper: users can inspect profile, resource, and wrapper resolution.
What felt rough
1. The opening is technically accurate but undersells the use case
Current opening:
This is accurate, but it may not immediately catch users who are dealing with the real problem runseal solves: repo-local execution with private resources and explicit wrappers.
A slightly more use-case-oriented sentence could help, for example:
That framing makes it easier to distinguish runseal from Makefile/just/direnv/dotenv.
2. The first example appears to have a bash invocation issue
README currently shows:
runseal --profile ./runseal.toml bash -- -lc 'echo "$RUNSEAL_PROFILE_PATH"'With
bash,--ends option parsing, so-lcis treated as a positional argument rather than an option. I think the intended example is:runseal --profile ./runseal.toml bash -lc 'echo "$RUNSEAL_PROFILE_PATH"'3. The strongest trust-building commands come too late
For a new user, these are very persuasive:
They answer the immediate questions:
resource://path become?:nameexecute?I would consider moving a short "inspect what runseal sees" block much earlier, before the full profile reference.
4. A 30-second repo-local example would help
The current profile example is comprehensive, but it mixes env, env ops, symlink, argv, and resources at once. A smaller first example may help users see the niche faster:
Then:
This shows the key idea: the repo declares a private resource root, runseal resolves it, and wrappers/scripts consume absolute paths instead of guessing repo-relative locations.
5. A sharper "fit / not fit" section would protect the tool's scope
The README already implies restraint, but an explicit section could help avoid mispositioning:
Fits well:
ssh,kubectl,uv,terraform, etc.Not trying to be:
direnvThat would make the design restraint more visible.
Suggested structure
One possible README flow:
@profile,@wrappers,@resolve):wrapper /@internalWhy this matters
The current README gives enough technical facts to use runseal, but the first-contact path requires the reader to already understand the niche. A small narrative pass could help the right users recognize the tool quickly: people with repos full of
.local,.env, kubeconfig/SSH config paths, wrapper scripts, and README instructions like "export these variables before running deploy".