# Guida Enterprise 0.2.0-alpha.1 Guida Enterprise brings source code, extraction tests, record design and product APIs into a shared, self-hosted workspace. This alpha is for guided evaluation on an operator-prepared installation. ## Choose your downloads | Download | Purpose | | --- | --- | | `Guida.Workspace.TestRunner-0.2.0-alpha.1-win-x64.zip` | Execute saved Studio drafts, including HTTP and headed-browser tests. | | `Guida.Enterprise.Node-0.2.0-alpha.1-win-x64.zip` | Run enrolled, authorized Enterprise jobs from signed source revisions. | | `Guida.Workspace.Authoring.Cli-0.2.0-alpha.1-win-x64.zip` | Authoring and candidate-export command-line tools. | | `Guida.Enterprise.Release-0.2.0-alpha.1-win-x64.zip` | Offline release/signing tools used in the reviewed publication handoff. | | `Guida.Enterprise.LocalNodeBootstrap-0.2.0-alpha.1-win-x64.zip` | Node bootstrap helper for the local development identity setup. | | `Guida.Enterprise-0.2.0-alpha.1-evaluation-guide.zip` | This guide and the synthetic first-draft example files. | | `docker-images.json` | Exact Linux image references for this build. | | `enterprise-candidate.json` | Original build inventory, including package hashes and image digests. | | `migration-plan.json` | The database migration plan from this candidate's migration image. | | `*.cdx.json` | CycloneDX dependency inventories for the Windows packages. | | `SHA256SUMS` | SHA-256 checksums for all the other release attachments. | Windows programs are self-contained x64 packages. Extract each program to its own directory. Headed-browser execution also requires an interactive Windows desktop and WebView2. Server images target Linux amd64. The draft runner and Enterprise Node serve different actions. Use the draft runner for **Test draft**. Use Enterprise Node for enrolled execution after signing and publication. ## Collection and worker roles The Linux `document-worker` image has three explicit modes: | Mode | Work | | --- | --- | | `--mode document` (default) | Extract records from an admitted retained document. | | `--mode discovery` | Execute an authorized API discovery stage and retain its full result stream. | | `--mode capture-http --workspace ` | Acquire an admitted HTTP capture and preserve its response and receipt. | Provision a separate enrolled Node identity, approved capabilities, credentials and persistent state for each role. All modes require the configured API origin, tenant, Node, token file, recovery-key file, public signing-trust file and state root. Run the container with an init process (`docker run --init` or Compose `init: true`). Preserve its state volume and recovery key across updates. Worker startup alone does not approve a source, a capture or downstream execution. Windows browser discovery uses the **Enterprise Node** package. The operator provisions its named instance, encrypted client-secret reference, renewable credential profile and public signing-trust file first. From that package, use PowerShell 7.2 or newer to preview the exact launch: ```powershell ./Start-BrowserDiscovery.ps1 -Mode Preview -Instance browser-discovery ` -CredentialProfile 'C:\GuidaPrivate\browser-discovery\credentials\profile.json' ` -RevisionTrustFile 'C:\GuidaPrivate\browser-discovery\trust\public-roots.json' ``` Replace these paths with the operator's protected configuration. Use `-Mode Start` to launch or `-Mode InstallShortcut` to configure minimized startup at interactive logon. Keep the package in an operator-controlled directory. Closing status minimizes it; restore it from the taskbar. **Show browser** restores browser surfaces. **Exit Node** stops the host while preserving unfinished work. Preserve the original named instance when recovering an interrupted attempt. In the Console, **Operations → Source schedules** reviews the exact signed source, typed input, domains and cadence. The installation scheduling gate, source approval, consumer routing, capture approval and document execution each retain their own authority. Enabling one does not enable the others. Keep these gates closed until the operator reviews the intended collection and resource budgets. ## Prepare the installation The operator configures the API and Console, PostgreSQL, persistent artifact storage, identity and HTTPS, then connects the matching Windows execution host. Use the exact digests in `docker-images.json` when selecting server images. For Studio testing, the API must be able to reach the draft runner's HTTPS address. Configure its credential, certificate trust and exact tenant/workspace scope on both sides. An address using `localhost` inside a container refers to that container. Configure the actual host-reachable address and matching certificate. Ask the operator for: - The Console URL and sign-in method. - Your evaluation workspace and a dedicated draft. - A connected draft runner. - The installed build identifier and a support contact. Use a desktop browser with a viewport at least 1600 pixels wide. A complete self-service installation bundle is in preparation; these downloads provide the components and tutorial for the guided alpha. ## Upgrade from 0.1.0-alpha.1 This release contains PostgreSQL migrations 001–088; the first alpha contained 001–059. The 29 additions support larger documents and workspaces, discovery, consumer handoffs, capture and recurring source scheduling. Existing migration scripts retain their original bytes. The migration runner checks the applied history and exact plan; do not edit migration history to force an upgrade. 1. Record the old image digests, Windows package locations, configuration and installed schema. Review all original pending commands, leases, retained results and worker journals. Pause new scheduling/admission and stop writers through supported controls. Preserve uncertain attempts for recovery. 2. Take a coordinated backup of PostgreSQL, artifact storage, identity and TLS configuration, signing material, worker state and recovery keys. Include any external consumer/evidence stores in the installation's recovery plan. Keep the old packages and configuration with this backup. A database-only backup cannot reconstruct pending worker or consumer work. 3. Download the complete matching release and verify `SHA256SUMS`. Read the seven digest-pinned references from `docker-images.json`; do not assume a mutable `latest` or semantic Docker tag exists. Replace API, Console and worker images together, keeping identities, volumes, secrets and approvals intact. Do not run the local seed against an existing workspace as an upgrade step. 4. Before starting new writers, run the new migrations image's `plan` command with no database connection and compare it with `migration-plan.json`. Have the operator apply that exact reviewed plan through the installation's private database connection: ```text plan apply --connection-env GUIDA_ENTERPRISE_CONNECTION --confirm ``` For the container image, these arguments follow its digest reference; its entrypoint already selects the migration program. Supply the connection through the reviewed environment/secret configuration, not a command-line value or shared transcript. A checksum or history mismatch requires review. 5. Start the matched API/Console and verify health and actual operator sign-in. Start each worker against its original identity and state. Reconcile pending commands and results before allowing new claims; do not delete journals or create replacement campaigns to clear recovery-required work. Update Windows shortcuts to the new extracted package while keeping the same instance. 6. With the operator, verify one authorized source through its expected consumer outcome and inspect its retained receipts. Reopen only the reviewed source and downstream approvals, then check the next scheduled occurrence if applicable. If rollback is needed, stop the new writers and preserve their current state before changing anything. Restore the matched pre-upgrade backup, configuration and old binaries together. Do not run 0.1 binaries against the upgraded catalog or manually remove migrations. Reconcile any external effects produced since the backup so recovery cannot duplicate work or delivery. The local migration has incremental upgrade and isolated restore evidence. A fresh end-to-end 0.1-to-0.2 installation/rollback has not been qualified as a self-service procedure; arrange the upgrade with the evaluation operator. ## Prepare the example in Studio The evaluation-guide ZIP contains `examples/collect.mjs`, input/output schemas and `expected-result.json`. The example returns one synthetic record and makes no network or model calls. 1. Open the dedicated draft in **Workspace Studio**. Beside **Sources**, choose **Add source**, then **Write a custom source**. 2. Set **Source name** to `First draft example`, **Collect with** to **API / HTTP requests**, **Default URL** to `https://example.com/`, and **Target domains** to `example.com`. The URL is a declared placeholder; the example code makes no request to it. 3. Under **Source identity and files**, use `first-draft-example`. Choose **Create source and write code**. 4. Replace the generated `lib/first-draft-example.js` implementation with the contents of `examples/collect.mjs`. Keep the generated `.js` filename and `collect` export. 5. In **Files**, replace `schemas/first-draft-example-input.schema.json` and `schemas/first-draft-example-output.schema.json` with the supplied schema contents. Save both. 6. Keep the generated descriptor references and `guida.extractorResult.v1` result envelope. The input schema accepts both `{}` and the source's configured URL default. ## Run, change and correct 1. Open the implementation and select **Test draft**. Use `{}` where input is requested. 2. Choose **Save and run draft**. Inspect the returned record: `id` should be `example-1`, with title `My first draft result`. 3. Change the title in the code to `My corrected draft result`. Save and run again, then confirm the changed value. 4. In this disposable example, replace the implementation with the following code and run it: ```javascript export async function collect() { throw new Error('Tutorial: deliberate failure'); } ``` 5. Read the reported error and follow its source location when available. Restore `examples/collect.mjs`, run again and confirm the expected record. You can now use a successful draft sample to define record fields, map source output and preview a product API. Publication and activation are separate reviewed steps. ## If you get stuck - **Runner unavailable:** preserve your edits, have the operator restore the runner connection, then select **Refresh**. - **Sign-in or certificate error:** have the operator correct identity, hostname or trust configuration for the intended connection. - **Save conflict:** review the latest saved version before reconciling changes. - **Long-running test:** select **Stop test**, wait for its terminal state and inspect the code before rerunning. - **Wrong output:** check the saved version, test input and returned record fields. AI assistance is optional and experimental. Start with the manual workflow above. Provider setup and model use are separate from this exercise. The runner executes trusted code. Use a dedicated evaluation workspace and agree on any real source access with the operator. Keep credentials and private records out of shared bug reports. ## Image and package identity The original `enterprise-candidate.json` records the build source and its seven images and five Windows packages. The accompanying `docker-images.json` presents the same images as digest-pinned pull references. Check attachment hashes against `SHA256SUMS` before use. The software packages retain their original proprietary notices and third-party dependency inventories. Arrange evaluation access and terms with the maintainer or installation operator.