# THIS YOU — ISSUE PACKAGE ARCHITECTURE v2

## Goal

Keep the engine stable and keep every magazine isolated.

```text
/engine
  /lib
  /admin
  /layouts        # global fallbacks only
  /themes         # global fallbacks only

/issues
  /_template
  /new-york-autumn-2026
      manifest.json
      issue.json
      chapters.json
      pages.json
      theme.css
      /layouts
      /assets
      /docs
```

## Rendering

Renderer asks the current issue package for its requested layout first.
If the issue package does not provide it, the engine falls back to a global layout.

This means Issue 02 can have a completely different design without changing Issue 01.

## Shared vs personalized

The issue folder contains the portable **shared issue master**.
Reader-generated images/text stay in the existing reader / user_issue generation system and do not modify the shared package.

## Creating a new issue

1. Admin → **Packages**.
2. Download the Issue Template ZIP.
3. Extract it and rename the folder to the new slug.
4. Fill JSON / layouts / assets / theme.
5. Either copy only that folder to `/issues/`, **or use Admin → Packages → Upload Package Folder**.
6. Admin → Packages → Validate / Dry Run / Sync to DB.

No issue package files should ever be copied into project root, `/assets`, `/layouts`, or `/themes`.

## Upload without ZipArchive

The current Windows PHP build does not have ZipArchive, so the system does not depend on server-side ZIP extraction.

Admin → **Upload Package Folder** uses the browser directory picker and uploads files sequentially. This avoids both ZipArchive and PHP's usual `max_file_uploads` limit for a whole magazine. Existing package replacement creates a folder backup first.

The downloadable template remains a ZIP because Apache only has to serve that static file; PHP does not need to open it.

## One-time Issue 01 migration

After copying this patch, open:

`/admin/migrate-issue-packages-v2.php`

Review its dry-run cleanup list, then press **MIGRATE + CLEAN DUPLICATES**.

It:
- validates the new Issue 01 folder;
- backs up Issue 01 DB rows;
- changes Issue 01 page layout keys to the real package-local keys;
- changes STORY shared image paths to `/issues/new-york-autumn-2026/assets/...`;
- SCENE pages become live issue-local HTML/CSS layouts and no longer use flattened preview images;
- removes only duplicate files whose package equivalents can be verified;
- removes the now-obsolete Issue-01-specific global render patch files.

## Cleanup safety

The Issue 01 migration does not blindly delete similarly named folders.

- legacy duplicate directories are removed only when every file is either byte-identical to the new issue package or matches the recorded hash of an obsolete flattened Scene/source artifact;
- known one-off root/import/global patch files are removed only when their SHA-256 matches the version inspected from the uploaded project;
- modified or unknown files are listed under **Skipped for safety** and left untouched;
- a database backup is written before DB page paths/layouts are relinked.

The canonical v2 Issue 01 package deliberately excludes the old flattened Scene preview images and the old Page 06 Scene HTML source copy. The six Scene pages now render from issue-local live layouts and individual object assets.