HydraIssues

Issues / #483
hydramancer: add an experience-publishing guide (/experience) — the second creator front door
closed feature Project: hydramancer Reporter: 12 Aug 2026 12:12

Description

Proposal: add an experience-publishing guide (/experience) to hydramancer

hydramancer is the Creator Onboarding Portal, but it currently only surfaces ONE
of the two creator paths. The /deploy page (added recently) covers backend/
microservice developers: containerize → push to scaleregistry → launch as a scale
→ label a domain → live with HTTPS. Good.

The other path — arguably the primary creator audience — is missing: game/
Unreal developers who build an interactive experience that gets streamed to
venues. The portal's landing has a HydraUnrealEngine card that gestures at the
packaging tool, but there is no walkthrough of the end-to-end pipeline, and a
creator who lands there is shown a microservice deploy guide that does not apply
to them.

The experience pipeline (what the guide should cover)

Perforce (source control — real UE source lives in the depots)
  └─ hydraunrealengine package     Windows: preflight checks (incl. Perforce state) + package the UE build
       └─ --deliver                chunked upload to HydraTransfer
            └─ hydraexperiencelibrary   register the build as an experience
                 └─ streamed to venue heads   (hydrahead / moonlight path)

It is already documented — just not in the portal

The real end-to-end guide exists at
hydraexperiencelibrary/docs/getting-started.md ("Getting Started: Publishing
Content" — package → upload → register), backed by the hydraunrealengine and
hydraperforce runbooks. The content is solid; it is only in a repo, not on the
onboarding portal, and not distinguished from the microservice path.

Proposal

Add a second hydramancer page — /experience — mirroring the /deploy pattern
(same template/handler/styling), walking the Perforce → package → deliver →
register → stream pipeline. Source it from getting-started.md plus the preflight
gotchas that bite in practice (e.g. #441: a project with no Source/ gave a false
preflight all-clear on exactly the shape that ships plugin source — Rupelmonde
Castle Viewer). Update the landing to present two clear front doors:

  • Ship a service (/deploy) — backend devs, container → scale
  • Publish an experience (/experience) — creators, Unreal → streamed

Also worth folding in (from the /deploy work)

The /deploy page still assumes the dev already has push/DNS access. For external
creators, the access hand-off (registry push token, Perforce depot access, who
approves a venue slot / experience registration) is the piece neither guide covers
yet — the natural next layer for a portal whose job is literally onboarding.

Scope

Documentation/portal only; no pipeline changes. One new template + handler +
landing link, same as /deploy. Low risk, high onboarding value.

Comments (4)

claude-ops 12 Aug 2026 12:20

Implementation plan (revised scope)

Agreed on the direction: two clear front doors is better than today's landing, which mixes a microservice "Deploy a service" CTA with experience content. Below is a concrete plan. It corrects two stale premises and resolves a naming collision the original proposal could not have known about.

Two corrections to the premise

  1. The landing is no longer "only a HydraUnrealEngine card". As of hydramancer v0.2.1 (deployed) it has a "Two ways to deliver a build" section with a HydraUnrealEngine card and a Perforce delivery card. Start from current master.
  2. Delivery is not just "chunked upload to HydraTransfer". There are three real variants today: rsync to the release server (what getting-started.md actually shows), HydraTransfer (used for the first Gallo-Romeins delivery), and Perforce auto-publish (hydraperforcewatcher). The page must state which is canonical, not inherit the doc's release-server assumption.

The key insight: Perforce has two roles, and that is fine

"Perforce" means two things and the page must hold both without contradiction:

  • Source control at the start of the pipeline (UE source in depots; hydraunrealengine reads P4 state in preflight).
  • An automated delivery + staging trigger at the end. getting-started.md already documents this as "Automated Staging (Perforce Workflow)": submit a build to a depot, HydraPerforce/hydraperforcewatcher notifies ExperienceLibrary via POST /api/v1/builds/notify, and the experience auto-stages. The experience is tied to the watch by the --watch <target> flag (e.g. --watch galloromeins for the live Gallo-Romeins/Cyborn setup).

So /experience presents ONE lifecycle (draft -> staging -> live) with TWO delivery modes into it: manual (package + upload + register) and automated (Perforce depot + watcher). The v0.2.1 landing cards are these two modes; they should move into /experience, not stay on the landing.

Deliverables

  1. Landing restructure (internal/web/templates/index.html)

    • Replace the single hero CTA with two front doors: "Ship a service" -> /deploy (backend devs, container -> scale) and "Publish an experience" -> /experience (creators, Unreal -> streamed).
    • Move the "Two ways to deliver a build" cards off the landing and into /experience. Leave a one-line teaser linking to /experience.

  2. New /experience page (mirror the /deploy pattern exactly)

    • internal/api/server.go: add GET /experience -> s.webExperience (mirror webDeploy, nil data).
    • internal/web/templates/experience.html: reuse deploy.html's structure (.lead, numbered .steps, .result, .gotchas).
    • Content sourced from hydraexperiencelibrary/docs/getting-started.md (the source of truth; keep the portal in sync with it, same rule the runbook already states for the hydraunrealengine download line):
      • Pipeline overview: Perforce -> package (hydraunrealengine) -> deliver -> register -> stage -> promote -> stream.
      • Delivery mode A (manual): package with hydraunrealengine (preflight), deliver to the CANONICAL target, hydraexperiencelibrary create -> stage --cl -> promote -> verify.
      • Delivery mode B (automated Perforce): submit to a stream depot -> watcher notifies -> auto-stage via --watch -> promote. Point to the Gallo-Romeins runbook + getting-started doc as the worked example.
      • Lifecycle diagram + command table (create/stage/promote/rollback/pause/resume/retire) from the doc.

  3. Header nav (internal/web/templates/layout.html)

    • Add two links in the header so both doors are always reachable: Ship a service, Publish an experience.

  4. Gotchas that actually bite (in the .gotchas block)

    • #441: a project with no Source/ gave a false preflight all-clear on exactly the shape that ships plugin source (Rupelmonde Castle Viewer). Do not trust a green preflight on a Blueprint/plugin-only layout.
    • GameplayStateTree enabled on a Blueprint-only project forces compilation; use --no-compile or disable the plugin.
    • Stream depots need a stream-bound client to submit; keep Binaries/, Build/, Intermediate/ out of source, but NOT Binaries/ThirdParty/ (redistributables).

  5. Access hand-off (short section, high value)

    • Document who grants what: registry push token (SCALE_REGISTRY_TOKEN), Perforce depot + account (admin, via hydra_admin), venue slot + experience registration approval (ExperienceLibrary owner). State plainly that this is manual today.

Out of scope (file separately)

Provisioning automation for the access hand-off (auto-create depot/account, mint a push token, reserve a venue slot) is the real fix behind item 5 but is a pipeline change, not a portal page. File as its own issue; this ticket stays docs/portal only.

Ship it

Same path as v0.2.1: tag v0.2.2 -> CI builds the multi-arch OCI image -> rebuild the Pi container (incus rebuild scaleregistry:hydramancer:v0.2.2 hydramancer --force) -> verify the live page. Update the hydramancer runbook's Delivery paths section to point at /experience.

Effort

Low code risk (one route + one template + two edits, all mirroring /deploy). The real work is editorial coherence: one Perforce story, one canonical delivery target. Roughly half a day.

claude-ops 12 Aug 2026 12:28

Out-of-scope item 5 (provisioning automation for the access hand-off) filed separately as #484. This ticket stays docs/portal only. Implementation of the /experience page is starting now per the plan above.

claude-ops 12 Aug 2026 12:46

DONE 2026-08-12 — shipped in hydramancer v0.2.2, live at hydramancer.experiencenet.com.

  • New /experience front door (route + webExperience handler mirroring /deploy, new experience.html). Presents one lifecycle (draft->staging->live) with two delivery modes: A manual (package -> rsync to releases -> create/stage/promote) and B automated Perforce (submit packaged build to depot Builds/ -> hydraperforcewatcher publishes + auto-stages via the experience --watch target -> promote). Includes the lifecycle diagram, command reference table, and the hard-won gotchas (#441 preflight false-clear, GameplayStateTree, stream-bound client, Binaries/ThirdParty).
  • Landing restructured into two front doors (Ship a service /deploy, Publish an experience /experience); the v0.2.1 delivery cards moved onto /experience. Header nav added on all pages.
  • Content sourced from hydraexperiencelibrary/docs/getting-started.md; runbook Delivery paths section updated.

Built via an ultracode workflow (design -> implement -> adversarial review -> fix). Reviewers caught a canonical-command carrying --skip-preflight (fixed) and Mode B inaccuracies (corrected: the dev still packages; Perforce replaces the deliver+stage steps, not package; watcher named hydraperforcewatcher). Verified live: /, /experience, /deploy, /api/v1/health all 200; both doors present; old section gone.

Safe to close. Provisioning automation remains in #484.

claude-ops 12 Aug 2026 14:06

Closed. Final live state is hydramancer v0.2.3: /experience opens with three entry points (in the browser via hydraunrealengine serve + ExperienceLibrary /admin; from the CLI = mode A; automated via Perforce = mode B), with the web equivalents woven into mode A and the CLI-only boundary (create + first stage) stated. Follow-up provisioning automation stays open in #484.