WickedSpooky.ai: Git, Amplify and Release Flow

Scope and current state

This runbook covers only the WickedSpooky.ai presentation site and its Creator training lab. It does not deploy the future Creator application. Written October 8, 2026; AWS deployment evidence remains pending.

The owner currently uploads ZIP files to Amplify without a Git connection. The original staging environment worked. A newly added production environment returned 404. After staging was deleted and an iLab environment was created, iLab also returned 404. These are owner-reported symptoms, not a verified root cause.

GitHub main contains the assembled website under public/, including index.html and labs/creator/. The architecture branch contains only README and Git attributes and is not a deployable website. There is no repository amplify.yml. No AWS credentials are configured in this workspace, so app IDs, branch deployment status, artifact contents, domain associations and DNS have not been inspected.

An Amplify manual hosting branch is an environment label. It does not become a Git branch through naming, and creating a new hosting branch does not upload the previous branch's files. Deleting and recreating a branch requires a fresh deployment and verification of its domain association. A ZIP is a snapshot of files, not proof of which Git revision produced it.

Target mapping for this site

These branch names and domain mappings are a proposed target, not a claim that AWS or Git has been configured. Existing main currently contains the latest lab updates; it must first be evaluated as a release candidate. Do not connect an unreviewed main revision directly to Production merely because its name is main.

Use one Amplify application with two hosting branches for this static site as the initial low-cost arrangement. Keep repository, artifact folder and rendering rules consistent. A separate production app/account becomes appropriate when permissions, backend data, secrets, release ownership or blast-radius requirements demand stronger isolation. Hosting branches alone do not isolate every AWS resource.

The iLab hostname can remain stable while its underlying branch is named qa. Branding and branch names serve different purposes. Avoid repeatedly deleting or renaming environments to change the public label.

Recover the current manual deployments first

Step 1 — Inventory the existing app. In the Amplify console, record the app ID, AWS Region, platform, every hosting branch, default branch URL, latest successful deployment/job and custom-domain association. Export or record current settings and retain the last working ZIP before changing anything. Do not delete branches or change DNS during diagnosis.

Step 2 — Inspect the actual ZIP uploaded to each environment. The archive root must contain index.html, assets/, landing.css and labs/ directly. It must not contain only public/index.html beneath a public/ directory. Zip the contents of public/, not the public/ directory itself. The archive name public.zip is not evidence of correct layout or current content. The ZIP checked into GitHub may be older than the current public/ tree.

Step 3 — Upload the verified ZIP to the intended manual hosting branch and wait for a successful deployment. Verify that branch's default amplifyapp.com URL at /, /impact.html, /labs/creator/ and /labs/creator/day-1/index.html. Confirm artwork and stylesheet requests also succeed. Use explicit index.html paths when checking whether a directory-route problem is involved.

Step 4 — Only after the default branch URL works, verify the custom-domain association. Map ilab to the QA/UAT hosting branch and the apex wickedspooky.ai to Production. Confirm that no association points to the deleted staging branch. Record certificate/domain status and the required DNS records from Amplify rather than guessing a destination. Check any configured www alias or redirect separately.

Step 5 — Diagnose by evidence. If the default branch URL also fails, inspect deployment status, ZIP root and published artifact paths. If the default URL works but the custom domain fails, inspect domain-to-branch mapping, DNS, certificates and redirect rules. If only nested routes fail, inspect their files and directory/index resolution. Do not hide missing pages behind a catch-all 200 rewrite: this is a multi-page static site, not a single-page application.

Move to Git-connected deployment

Connect the selected GitHub repository through the official Amplify GitHub App and grant access only to the required repository. The owner completes any new account/installation authorization. A newly created Git-connected Amplify app provides a clear migration path when the existing manual app cannot be connected through its supported settings. Keep the old working deployment available until the new app's default URLs and domain transition have been verified.

Create qa from the intended baseline and evaluate the candidate there first. Protect main against routine direct changes, require pull-request review and meaningful build checks, and keep feature branches short-lived. The proposed flow is feature/topic → qa → accepted release → main. Use a fast-forward or controlled merge when possible; if the main release commit differs from the tested candidate, validate the exact main revision before publishing it.

Enable automatic builds for qa. Initially disable automatic builds for main and explicitly release an approved main revision. After branch protection and release checks are enforced, automatic production builds on approved main merges are a simpler option. Record the deployed commit SHA, build/job ID and acceptance evidence for each release. A tag is a reference to the accepted revision; it does not itself deploy the site.

Build and artifact contract

The existing site is static. The checked-in public/ tree is already assembled, so deploying it needs no npm install, frontend framework or Creator backend provisioning. Regenerate lessons when their canonical sources change, review the generated diff and run the existing verification before release. Site artwork generation is a separate editing workflow and must not run blindly in a deployment pipeline.

For a Git-connected build rooted at the repository, this is the minimal candidate build specification:

version: 1
frontend:
  phases:
    build:
      commands:
        - test -f public/index.html
        - test -f public/labs/creator/index.html
  artifacts:
    baseDirectory: public
    files:
      - '**/*'

The specification is an example, not active AWS configuration. For manual ZIP uploads, baseDirectory is not involved: Amplify publishes the archive contents. If an app root/build path is later configured, verify that the artifact path is still correct relative to it. Do not deploy repository-root docs, scripts or access policies as site artifacts.

Acceptance and rollback

Release acceptance requires the intended revision, successful deployment, correct home page, working lesson/navigation/assets, hover descriptions, Mermaid rendering or source fallback, and expected desktop/mobile behavior. Confirm the current signup versus approved-referral destinations and all Learn / Practice / Execute destinations. Opening Execute must only navigate to the console.

Store one acceptance record with revision, artifact checksum, app/branch/job, tested URLs, date, outcome and approver. Roll back by redeploying the previous accepted revision or verified archive using the supported app deployment flow. A Git revert can create a reviewed corrective release; avoid force-pushing release history. Do not delete the hosting branch as rollback.

After recovery, retire duplicate deployment paths deliberately. Git-connected publishing becomes the normal flow; manual ZIP deployment is a documented recovery option with revision and checksum evidence. Never maintain two competing sources of truth for the same environment.

Costs, isolation and fail-forward evidence

Start with two permanent environments and bounded builds. Branches do not provide a fresh Free Tier credit balance: account credits are shared, expire and cannot be the production profitability assumption. Track account-level costs and app build/storage/transfer usage, minimize duplicate rebuilds and remove temporary previews after review. Set budgets/alerts; alerts alone do not stop spending.

When a Creator backend is eventually added, explicitly separate QA/UAT and Production data, identities, secrets and billing integration environments. Test provider limits and human approval rules before accepting paid customers. That is a future application slice, not part of recovering this static training site.

Record this incident as a fail-forward investigation: previous working staging deployment; production 404; staging deletion and iLab recreation; ZIP structure; branch job status; default/custom-domain results; confirmed cause; corrective action; rollback; verification. Do not claim that ZIP nesting or domain mapping caused the failure until the evidence demonstrates it.

AWS references

Fail-forward finding: nested ZIP root

On October 8, 2026, read-only HTTP checks confirmed that the default Production and iLab branch URLs returned 404 at / and /index.html. Both returned 200 at /public/index.html. The same nested path returned 200 on wickedspooky.ai and ilab.wickedspooky.ai. This demonstrates that the site's index file was published beneath an extra public/ directory. Custom-domain routing reached the deployed content; branch renaming was not required to correct this artifact-layout issue.

The corrective artifact places index.html, assets/ and labs/ at the archive root, excludes Python build scripts, and includes the current static Creator lessons. Its archive layout was verified locally. Upload it to iLab first, verify the default and custom-domain root URLs, then promote the same accepted archive to Production. Deployment and post-fix HTTP verification remain pending; a prepared ZIP is not evidence that the live sites are restored.

AWS references

Manual deployments and ZIP root requirements

GitHub connection and repository authorization

Feature branches and team workflows

Build specification and artifact directory

Build settings and disabling automatic builds

Custom domains and branch URLs

Amplify pricing