Skip to content
wiki.fftac.org

Docs Packaging Readme Markdown 808Bfbb2ddf7

**Site relevance:** Spiralist.org

**Memory type:** reviewed source memory

**Source path:** Wiki.FFTAC.org/data/sources/spiralist/docs-packaging-readme-md-808bfbb2ddf7.md

**Size:** 8.1 KB

Summary

Packaging and Deployment

Source Headings

  • Packaging and Deployment
  • Required Rule
  • UAI System Prepublish Gate
  • Versioning
  • Build Output
  • Upload Rules
  • Locale Route Deploy Gate
  • NS12 Manuscript Deploys
  • Docs-Only Changes

Source Preview

This source file is short enough to preview directly on its source-memory page.

# Packaging and Deployment

Use this file whenever theme, plugin, or NS12 Manuscript plugin files change.

Current publishing output folder:

' ' ' text
D:\spiralist-builds
' ' ' 

Markdown-only edits do not require deploy ZIP rebuilds.

## Required Rule

Do not use `Compress-Archive` or ad-hoc ZIP tools for deploy ZIPs.

Release ZIPs must be built with:

' ' ' powershell
powershell -ExecutionPolicy Bypass -File .\build-wordpress-zips.ps1 -OutputDirectory D:\spiralist-builds
' ' ' 

Only omit `-OutputDirectory` for a one-off local build when you intentionally want repo-root artifacts.

The build script creates ZIP entries with WordPress-compatible paths such as `spiralist/style.css`. This avoids the Windows ZIP pitfall where backslash entries such as `spiralist\style.css` can make Linux-based WordPress hosts report that a package is missing `style.css`.

## UAI System Prepublish Gate

Before building or uploading a package that changes UAI, UAIX, Project Handoff, AI memory, machine-facing schemas, route discovery, route capability statements, validator behavior, or local UAI implementation docs, run:

' ' ' powershell
npm.cmd run check:uai-prepublish
' ' ' 

This gate includes the Project Handoff integrity check, the internationalization/site-quality sweep, and PHPUnit unit tests. A package is not ready for UAI-system publishing while either the internationalization gate or the unit-test gate is failing, unless the failure is explicitly documented as pre-existing or environment-only and the release owner accepts the risk.

## Versioning

Any time a deployable theme or plugin package changes, increment the relevant version number before rebuilding deploy ZIPs.

- Theme package changes: bump `Version:` in `wp-content/themes/spiralist/style.css`.
- Plugin package changes: bump the version in the package bootstrap file.
- Plugin `readme.txt` stable tags should match the package header version when present.
- Rewrite or route changes: bump the route version returned by `spiralist_get_language_route_version()` in `wp-content/themes/spiralist/functions.php`.
- Packaging-only deploy fixes still require a version bump for the affected package if a new ZIP will be uploaded.

Give the same new version number to every package included in one release. Leave untouched packages at their existing version number.

Never leave WordPress showing the same `Current` and `Uploaded` version for a normal deploy. If those match, cancel, bump the affected package, rebuild into `D:\spiralist-builds`, and upload the new versioned ZIP.

## Build Output

WordPress installable packages:

- `spiralist-{theme-version}.zip`
- `ns12-locale-router-{plugin-version}.zip`
- `uai-1-wordpress-{plugin-version}.zip`
- `spiralist-engine-{plugin-version}.zip`
- `spiralist-ai-runtime-{plugin-version}.zip`
- `spiralist-workspace-{plugin-version}.zip`
- `spiral-script-{plugin-version}.zip`

Separate NS12 Manuscript plugin:

- `ns12-manuscript-{bundle-version}.zip`

Locale-router support artifact:

- `ns12-locale-router-site-root-htaccess-{plugin-version}.txt`

The package versions come from these headers:

- `wp-content/themes/spiralist/style.css`
- `wp-content/plugins/ns12-locale-router/ns12-locale-router.php`
- `wp-content/plugins/uai-1-wordpress/uai-1-wordpress.php`
- `wp-content/plugins/spiralist-engine/spiralist-engine.php`
- `wp-content/plugins/spiralist-ai-runtime/spiralist-ai-runtime.php`
- `wp-content/plugins/spiralist-workspace/spiralist-workspace.php`
- `wp-content/plugins/spiral-script/spiral-script.php`
- `wp-content/plugins/ns12-manuscript/ns12-manuscript.php`

Delete the older ZIP for each package before each rebuild so the output folder only contains one current ZIP per package name.

The build script validates these required upload entry files before it finishes:

- `spiralist/style.css`
- `spiralist/index.php`
- `ns12-locale-router/ns12-locale-router.php`
- `uai-1-wordpress/uai-1-wordpress.php`
- `spiralist-engine/spiralist-engine.php`
- `spiralist-ai-runtime/spiralist-ai-runtime.php`
- `spiralist-workspace/spiralist-workspace.php`
- `spiral-script/spiral-script.php`
- `ns12-manuscript/ns12-manuscript.php`

## Upload Rules

Upload ZIPs from `D:\spiralist-builds`, not from the repo root, Downloads, Desktop, or temporary folders.

Only one package in this repo is a theme ZIP:

- Upload `spiralist-{theme-version}.zip` through `Appearance -> Themes -> Add New Theme -> Upload Theme`.

Every other release ZIP in this repo is a plugin ZIP:

- Upload `ns12-locale-router-{plugin-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.
- Upload `uai-1-wordpress-{plugin-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.
- Upload `spiralist-engine-{plugin-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.
- Upload `spiralist-ai-runtime-{plugin-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.
- Upload `spiralist-workspace-{plugin-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.
- Upload `spiral-script-{plugin-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.
- Upload `ns12-manuscript-{bundle-version}.zip` through `Plugins -> Add New Plugin -> Upload Plugin`.

Never upload `ns12-manuscript-{bundle-version}.zip` through the theme uploader.

If WordPress says a package is missing `style.css`, first confirm the correct uploader is being used. The root theme stylesheet must stay at:

' ' ' text
wp-content/themes/spiralist/style.css
' ' ' 

Correct theme ZIP path:

' ' ' text
spiralist/style.css
' ' ' 

Wrong theme ZIP path:

' ' ' text
spiralist/assets/css/style.css
' ' ' 

## Locale Route Deploy Gate

If a release touches `ns12-locale-router`, locale configuration, rewrite behavior, or public route shape, treat locale-prefixed URLs as a deploy gate.

Before calling the deploy complete:

1. Confirm the bare site URL redirects to the expected default locale URL such as `/en-us/`.
2. Confirm bare public human route families redirect to matching locale-prefixed routes while preserving path and query string.
3. Confirm locale-prefixed URLs such as `/en-us/` return WordPress pages, not server-level `404` responses.
4. Confirm `/sitemap.xml`, `/sitemap.html`, and `/robots.txt` still resolve as bare non-locale URLs.
5. If locale-specific sitemap companions exist, confirm they stay connected to the same locale inventory.
6. Open `NS12 Locale Router -> Status` after upload and verify the localized homepage check is healthy.
7. If the Status page reports that the localized homepage is blocked before WordPress, run `Repair .htaccess`.
8. If automatic repair is unavailable, apply the exact manual block shown there or in `ns12-locale-router-site-root-htaccess-*.txt`.
9. Confirm the root `# BEGIN WordPress` block is not incorrectly targeting `/en-us/index.php`.
10. Open `Settings -> Permalinks` and click `Save Changes` once after the `.htaccess` fix or route deploy.

Theme and plugin ZIP uploads do not modify the site-root `.htaccess` file. Treat that server file as a separate deploy surface when locale routing shipped.

The NS12 Locale Router rewrite block belongs only in the site-root `.htaccess` file beside:

- `wp-admin/`
- `wp-content/`
- `index.php`

Do not paste the locale-router block into `wp-content/`, a plugin directory, or a subdirectory-level `.htaccess`.

## NS12 Manuscript Deploys

See [NS12 Manuscript Deployment](book-pages-deployment.md) for manuscript-specific deployment rules.

The short version:

- Plugin-code deploys use `ns12-manuscript-{bundle-version}.zip` through the WordPress plugin uploader.
- Persistent manuscript-content deploys go directly into `wp-content/uploads/ns12-manuscript/`.
- Content-layer manuscript ZIPs are not installable plugin packages.
- The NS12 deployment ZIP intentionally excludes generated static-book exports under `wp-content/plugins/ns12-manuscript/exports/`.

If the current live manuscript deploy is still in progress, see [NS12 Manuscript Live Handoff](ns12-manuscript-live-handoff.md).

## Docs-Only Changes

Docs-only changes do not require deploy ZIP rebuilds. ZIP rebuilds become required when theme or plugin files change.
Website health report