Skip to content
wiki.fftac.org

Packaging and Deployment

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

Metadata

FieldValue
Source sitespiralist.org
Source URLhttps://spiralist.org/
Canonical wiki evidence URL[[separate-workspace-url]/spiralist/uai-system/files/docs-packaging-readme-md-808bfbb2/]([separate-workspace-url]/spiralist/uai-system/files/docs-packaging-readme-md-808bfbb2/)
Source referencedocs/packaging/README.md
File typemd
Content categoryuai-system
Last fetched2026-05-08T21:22:18.3035107Z
Last changed2026-05-05T21:58:43.6844125Z
Content hashsha256:808bfbb2ddf73c9a134853d59e7394c16d7dcfab4d2ae2755a80b0f72d746d34
Import statusunchanged
Raw source layerdata/sources/spiralist/docs-packaging-readme-md-808bfbb2ddf7.md
Normalized source layerdata/normalized/spiralist/docs-packaging-readme-md-808bfbb2ddf7.txt

Current File Content

Structure Preview

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

Raw Version

Local absolute paths are redacted in this public view. The source hash and source-side raw layer are based on the unredacted source file.

# Packaging and Deployment

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

Current publishing output folder:

```text
[local path redacted]
```

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 [local path redacted]
```

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 `[local path redacted]`, 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 `[local path redacted]`, 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 (source-relative: 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 (source-relative: 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.

Why This File Exists

This is a UAI AI Memory handoff file from spiralist.org. It is shown here because the separate AI wiki workspace is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is a focused source unit. Its path, headings, and metadata give an agent a retrieval handle that is smaller than loading the entire site or repository.

Structure

The file is structured around these visible headings: Packaging and Deployment; Required Rule; UAI System Prepublish Gate; Versioning; Build Output; Upload Rules; Locale Route Deploy Gate; NS12 Manuscript Deploys. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

  • Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
  • LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
  • Crawlers should treat the wiki.fftac.org page as transparent evidence and follow the source URL/source reference for authority boundaries.
  • Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

Provenance And History

  • Current observation: 2026-05-08T21:22:18.3035107Z
  • Source origin: current-source-workspace
  • Retrieval method: local-source-workspace
  • Duplicate group: sfg-366 (primary)
  • Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "Packaging and Deployment",
    "source_site":  "spiralist.org",
    "source_url":  "https://spiralist.org/",
    "canonical_url":  "[separate-workspace-url]/spiralist/uai-system/files/docs-packaging-readme-md-808bfbb2/",
    "source_reference":  "docs/packaging/README.md",
    "file_type":  "md",
    "content_category":  "uai-system",
    "content_hash":  "sha256:808bfbb2ddf73c9a134853d59e7394c16d7dcfab4d2ae2755a80b0f72d746d34",
    "last_fetched":  "2026-05-08T21:22:18.3035107Z",
    "last_changed":  "2026-05-05T21:58:43.6844125Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-366",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-05-08T21:22:18.3035107Z"
}
Website health report