bare-operating-system/packages/bare-os-seeder/kernel/share/agent-workspace/skills/bare-os-super-developer/SKILL.md

name, version, description, tags, requires

name	version	description	tags	requires
bare-os-super-developer	1.0.0	Write Bare OS scripts and small apps using ctx — VFS, execLine, hooks, caps, and safe patterns (no Node in /bin/agent loop).	bare-os ctx scripts vfs kernel developer	read_file read_proc_file run_js_script

bare-os-super-developer — Scripts, apps, and ctx

When to use

Use this skill when you (or the user) need to author or debug Bare OS JavaScript that runs inside the guest (kernel init, /bin/* utilities, kernel.ext.d, user .mjs run via run_js_script**, or Pear/booter-hosted scripts). It complements repo docs: treat **developer-guide/02-the-context-object.md** and **packages/bare-os-booter/lib/bare-os-ctx.d.ts as the canonical deep dives; this file is the fast mental model.

Core model

1. Entrypoints — Kernel: async function start(ctx) in /boot/init.js (or your image). Commands: async function run(ctx, argv)** where **argv[0] is the invoked name (e.g. agent). You must set ctx.exitCode (number) before returning on failure paths.
2. ctx is not Node — There is no full process**, no **require('node:fs')**. The booter assembles **ctx** as the narrow syscall surface: **vfs**, **env**, **execLine**, **runBinCommand**, optional **httpFetch**, **bare, identity helpers, diagnostics, etc. See the mermaid overview in Chapter 2 of the developer guide.
3. /bin/agent is special — The agent bundle uses run_js_script** for guest JS and a frozen tool surface; do not assume **node** exists. For general in-guest scripting, prefer **ctx.vfs** + **ctx.execLine** / **ctx.runBinCommand** and optional **ctx.bare.* modules when enabled.

Writing scripts (run(ctx, argv))

• Argv — argv is a string array; argv[0] is how you were invoked (symlink name matters for multi-call binaries).
• Stdout — Prefer ctx.console.log** / **ctx.console.error** (session-aware). For binary or captured stdout, **ctx.bareOsBinWrite may exist when the shell captures pipeline output.
• Shell a subprocess — await ctx.execLine('some shell line', { signal, timeoutMs })** returns a string (see booter **raceWithAbortAndTimeout**). Heavy work: **await ctx.runBinCommand(['/bin/grep', …], opts) for same resolution as the interactive shell.
• Filesystem — await ctx.vfs.readFile(path)** → **Uint8Array**; **await ctx.vfs.writeFile(path, buf, opts?)**. Decode with **ctx.b4a.toString(buf)** or **TextDecoder**. Always use absolute paths under **/home**, **/tmp**, **/mnt**, **/bin, etc., per policy.
• Environment — ctx.env** is mutable shell state (also **ctx.vfs.env**). After **execLine**, **ctx.env.BARE_OS_EXIT_STATUS reflects last exit code when the booter sets it.
• Exit — Set ctx.exitCode = 1** (or other code) on error; **0** on success. **ctx.requestBooterExit(code)** ends the whole session from builtins like **exit.

Building “apps” (long-lived behaviour)

Think in layers the stock OS already uses:

Layer	Mechanism	Notes
Init	**bareOsRegisterBootStepHook**, initd units	Boot-order DAG (stock: **bare-os-www** before **bare-holesail** so **bare-www-*** reaches loopback HTTP; **bare-openssh** + login stack ensure **bare-ssh-*** in **~/.holesail/state.json**); pair **registerKernelShutdownHook** / initd disposers for teardown.
Virtual files	**bareOsRegisterVirtualFile(name, reader, opts?)**	Serves **/run/bare-os/virtual/<name>**; gated by runtime caps.
IPC	**ctx.bareOsIpc** when present	**push/take**, JSON helpers, fanout, duplex bridge — bounded; audit when **BARE_OS_IPC_AUDIT=1**.
Kernel extensions	bareOsRegisterKernelExtensionRecord**, **bareOsRunImageScript** under **/lib/bare-os/extensions/	Trusted image paths only.
Sandboxed user JS	**bareOsSandboxRunScript(source, argv?, opts?)**	Restricted **ctx**; disable with **BARE_OS_SANDBOX_SCRIPT=0**.
Pear / host	**bareOsPearIpcEmit**, **bareOsPearIpcRequest**, mirror/export hints	Host must cooperate; return **{ ok, hint }** patterns.

Before touching sensitive ctx** methods in hardened images, call **ctx.bareOsIsCtxMethodAllowed?.(name)** when boot policy **BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS is set.

ctx field map (cheat sheet)

Always read live truth for capability bits: read_proc_file** on **/proc/bare_os/features** and **/proc/bare_os/capabilities.json** — do not infer from man pages alone (see **bare-os-kernel-proc skill).

Files, drives, process

• ctx.vfs** — **readFile**, **writeFile**, **mkdir**, **readdir**, **stat/lstat**, **chmod**, … Path routing: system vs personal Hyperdrive; **ctx.drive** vs **ctx.personalDrive for advanced use.
• ctx.env**, **ctx.drive**, **ctx.personalDrive**, **ctx.disk — Session identity and mounts.
• ctx.execLine**, **ctx.runBinCommand — Shell and /bin execution with shared policy (timeouts, abort).

Bytes, console, session

• ctx.b4a — Buffer/string helpers for Hyperdrive payloads.
• ctx.console**, **ctx.readLine**, **ctx.writeScreen** — REPL session ( **readLine may be Fish-backed when enabled).
• ctx.exitCode**, **ctx.requestBooterExit**, **ctx.registerKernelShutdownHook

Bare OS introspection & policy

• ctx.bareOsCtxApiVersion**, **ctx.bareOsRuntimeCaps (frozen)
• ctx.bareOsAdvertisedKernelCapabilityWords**, **ctx.bareOsSeedKernelCapabilityWords** — **>>> 0 when testing bits.
• ctx.bareOsGetResourceStatus**, **ctx.bareOsReadProcMetricsLive**, **ctx.bareOsReadBareTopSnapshot
• ctx.bareOsRegisterVirtualFile**, **ctx.bareOsInvalidateVirtualFile**, **ctx.bareOsUpdateVirtualFileMeta
• ctx.bareOsEmitIpcAudit**, **ctx.bareOsEvaluatePeerAdmission**, **ctx.bareOsEmitMirrorDriveHint

Optional / host-dependent

• ctx.httpFetch** — Same allow/deny policy as **curl** / **wget**; every host for **web_fetch must be allowlisted.
• ctx.bare** — Frozen map of vendored modules (**b4a**, **protomux**, …) when **BARE_OS_BARE_MODULES allows.
• ctx.bareOsHostStats**, **ctx.bareOsChat***, **ctx.bareOsPearIpc* — Present only when wired by the booter/host.

For the full list and semantics, open developer-guide/02-the-context-object.md** in the repo (or **read_file on a mounted checkout).

Minimal script template (guest)

/**
 * @param {Record<string, unknown>} ctx
 * @param {string[]} argv
 */
export async function run(ctx, argv) {
  const argv0 = argv[0] || 'script'
  const vfs = ctx.vfs
  if (!vfs?.readFile) {
    ctx.console.error(argv0 + ': no vfs')
    ctx.exitCode = 1
    return
  }
  try {
    const buf = await vfs.readFile('/proc/bare_os/features.json')
    const t =
      ctx.b4a && typeof ctx.b4a.toString === 'function'
        ? ctx.b4a.toString(buf)
        : new TextDecoder().decode(buf)
    ctx.console.log(t.slice(0, 500))
  } catch (e) {
    ctx.console.error(argv0 + ': ' + (e && e.message ? e.message : String(e)))
    ctx.exitCode = 1
  }
}

Save under /home/.../my-tool.mjs** and run by absolute path (or register under **/bin** on the image). Do not rely on **node in the guest.

Agent-specific note

When helping inside /bin/agent, the model uses tools (read_file, run_js_script, …) backed by the same personal/system VFS as the rest of the guest. run_js_script** writes a temp **.mjs** under **~/.agent/** and executes it like a **/bin** script — the script body should use the same **ctx** patterns above when the harness passes **ctx.

Checklist before shipping

1. read_proc_file** / **get_system_info — confirm needed features and caps exist this session.
2. Paths — absolute, no .. escape from allowed roots.
3. Timeouts — pass AbortSignal** / **timeoutMs** to **execLine** / **readLine for network or slow FS.
4. Teardown — unregister hooks, clear intervals, dispose IPC fanout subscribers.
5. Secrets — never log ~/.agent/config.json** or keys; redact in **MEMORY.md.

Output format (when this skill was used)

• What you read — which ctx** fields or **/proc files grounded the answer.
• Plan — file paths, entrypoint (run vs start), and exit semantics.
• Risks — policy gates, missing caps, host-only APIs.