Serena GSD Bridge

Serena GSD Bridge is a repository for installing and validating Serena Native GSD Core setup surfaces, centered on the serena-setup helper.

Installation

Install the published package globally:

npm install --global @acidicsoil/serena-gsd-bridge
serena-setup init

For one-shot use without a global install:

npx @acidicsoil/serena-gsd-bridge init

Upgrade or uninstall it with npm:

npm update --global @acidicsoil/serena-gsd-bridge
npm uninstall --global @acidicsoil/serena-gsd-bridge

Quick start

1. Preview the install plan for the current project:

   serena-setup update --dry-run --json

2. Apply the safe local default:

   serena-setup init

serena-setup update

3. Install selected project skills non-interactively:

```bash
serena-setup init --target /path/to/project \
  --choices local,agent,skills \
  --skills gsd-browser-automation,gsd-frontend-skill-routing \
  --yes

The interactive init wizard presents the same skill list after the top-level Skills surface is selected.

Install scopes and types

Scope controls where modifications happen. Type controls how much gets installed within that scope.

| Option | Values | Meaning | |---|---|---| | Scope | local, global, all | local writes only target-project surfaces. global writes only user-global Serena surfaces. all explicitly writes both in one run. | | Type | min, standard, full | Amount of setup to install inside the selected scope. |

full does not mean global. Local full installs the full project-local layer set. Global full installs the full user-global layer set. Use --scope all --type full when bootstrapping both local and global surfaces together. The canonical preview command is update --dry-run; only init and update commands with canonical local, global, and all scopes and min, standard, and full types are supported.

What gets installed

| Scope | Type | Planned surfaces | |---|---|---| | local | min | Serena index command, project memory pointer, and managed agent instruction block. | | local | standard | Local min plus .serena/project.local.yml. | | local | full | Local standard plus the selected logical project-skill bundles and their manifest-owned support artifacts. A selected opengsd-docs-lookup bundle includes its skill, docs, and sync script; a selected gsd-frontend-skill-routing bundle includes its references. | | global | min | Minimal global memory pointer: native-gsd-core-serena/operating-rule.md. | | global | standard | Core global Serena mode plus the minimal operating-rule pointer memory. | | global | full | The current full user-global set from .serena-gsd/setup/manifest.json: serena-native-gsd-core.yml, gsd-browser-automation.yml, plus operating-rule.md, agent-instruction-resolution.md, inline-agent-substitution.md, role-boundary-protocol.md, workflow-gate-preservation.md, capability-routing.md, and result-honesty.md; differing managed files are canonicalized on apply. | | all | full | Local full plus global full in one explicit command. |

Project skill selection is persisted in <target>/.serena/skills-selection.json as direct logical skill IDs. Later update runs reuse that selection and do not expand to newly available skills. Targets from before this state file existed are migrated by detecting only manifest-owned skill entrypoints; unrelated user-owned skills are ignored and never deleted. Existing managed project-local artifacts are canonicalized by update; user-owned files outside manifest-managed targets are not overwritten. Existing user-global managed modes and memories are diffed; global full and all full canonicalize them on apply and prune stale managed serena-native-gsd-core* / native-gsd-core-serena/* files that are no longer in the manifest.

Project-local setup uses descriptor-relative, no-follow filesystem access and currently requires Linux or macOS; unsupported platforms fail closed rather than downgrading to race-prone path checks.

Default source order

The helper reads ~/.serena-gsd by default. A full home setup bundle can override the bundled setup. A simple home project.local.yml overlays the bundled/repo manifest, so local config is honored while the bundled managed global modes and memories still install. SERENA_SETUP_SOURCE_ROOT is the explicit source-root override and bypasses home lookup for that run.

The manifest at .serena-gsd/setup/manifest.json is the single source of truth for logical skill bundles, targets, ownership, policy, and source roots. Installable project payloads have one canonical copy: skills live under skills/, OpenGSD support docs live at docs/opengsd-agent-docs.md, and the docs sync helper lives at .serena-gsd/scripts/opengsd-docs/. The setup directory retains manifest metadata and setup-only modes, memories, and templates; it does not duplicate those project payloads.

Usage examples

Preview a default local install:

serena-setup update --dry-run

Apply a standard local install to another project:

serena-setup update --target /path/to/project

Install global full surfaces into the configured Serena home:

serena-setup update --scope global --type full

Use a setup bundle from a source checkout:

SERENA_SETUP_SOURCE_ROOT=/path/to/serena-gsd-bridge serena-setup update --dry-run --json

Main files

| Path | Purpose | |---|---| | cli.ts | TypeScript CLI source. | | lib/args.ts | Parses commands, scopes, install types, flags, and defaults. | | lib/install-plan.ts | Builds the dry-run/apply operation plan. | | lib/skill-selection.ts | Resolves manifest-backed skill bundles, dependencies, persistence. | | lib/operations.ts | Validates and applies staged operations. | | .serena-gsd/setup/manifest.json | Declares logical skill bundles, source roots, targets, scopes, ownership, and install policies. | | skills/ | Canonical source tree for installable project skills; do not add a second copy under .serena-gsd/setup/. | | docs/opengsd-agent-docs.md | Canonical source for the installable OpenGSD support document. | | .serena-gsd/scripts/opengsd-docs/ | Canonical source for the installable OpenGSD docs sync helper. | | install-flow.md | Short install-flow spec for scope/type semantics. |

Testing

Run the setup helper test suite:

npm ci
npm run typecheck
npm test
npm run pack:smoke

License

Licensed under the MIT License; see LICENSE.