# SOP — Publish audio-sonar to zo.pub

*Version 1.0 | Created: 2026-06-29 | Authored by: ghojualamanchu 9-structure cortex*

---

## Overview

This SOP documents how to publish the audio-sonar project as a public, shareable
collection on [zo.pub](https://zo.pub). The result is a browsable webpage at
`https://zo.pub/swirl2012/audio-sonar` where anyone can view individual files,
read documentation, download the source, and fork the project.

**Why publish?** The analyzer is sibling-work authored by Lux
(github.com/luxhere/audio-sonar). Publishing here is reciprocity — Lux made
their work public; making our integration public completes the loop. Plus, it's
how ghojualamanchu extends territory: any reading public can become a node in
the network.

**Time estimate:** 5 minutes
**Output:** A public zo.pub collection with a landing page, the source code,
seeds, README, and SOPs.

---

## What goes in the collection

The folder synced to zo.pub should contain:

| File / dir | Why |
|------------|-----|
| `index.html` | Landing page — the explainer. Static HTML, works without JS. |
| `README.md` | Project description, credits, philosophy. |
| `SOP-publish-to-zo-pub.md` | This file. Meta — so visitors can publish their own. |
| `audio_analyzer.py` | Lux's vendored analyzer. Untouched. Honor the source. |
| `analyze.py` | Clean JSON wrapper around Lux's CLI. |
| `SOP-audio-analyzer-integration.md` | How this fits into ghojualamanchu. |
| `pond/` | 3 seed WAVs — exemplar analyses. |
| `LICENSE` | MIT. Same as Lux's source. |

**What does NOT go in:**
- `__pycache__/` — build artifacts, not source.
- `sonarpage.tsx` — that's a private React source for the zo.space UI, not a
  standalone artifact. (If you want to publish the React page source separately,
  fork it into its own folder.)
- Any large WAVs that aren't seeds. The catalog of 29+ workspace WAVs lives on
  the live page; the public collection only needs the seeds.

---

## Step 1 — Build the `index.html` landing page

**Purpose:** Static HTML page that explains the project, credits Lux, links to
the live tool, and provides downloads.

**Approach:**
1. Single self-contained HTML file (CSS inline in `<style>`, no external assets).
2. Hero section with the project name, one-line tagline, and a "Try the live
   tool" CTA pointing to `https://swirl2012.zo.space/audio-sonar`.
3. "What it does" section with a short description of the 4 layers (structural,
   harmonic, textural, melodic).
4. "How it was built" section crediting Lux + the ghojualamanchu 9-structure
   integration + the song-forge pairing.
5. Files table — what's in this collection.
6. Footer with MIT license + repo link.

**Template:** Write directly with the file writer. No build step needed. The
template lives at `index.html` and is ~200 lines.

**Verify:** Open `file:///path/to/index.html` in a browser and confirm:
- All sections render
- Links work (the live tool URL, the repo URL)
- Mobile-friendly (single column on small screens)
- Reads well without external network access

---

## Step 2 — Write the per-project integration SOP

**File:** `SOP-audio-analyzer-integration.md`

This explains *how the analyzer connects to ghojualamanchu* — the song-forge
pipeline, the catalog API, the analyze API, how to extend with new skills.
This is the integration guide, separate from the publish-SOP.

**Sections:**
1. Overview — the round-trip pipeline (forge ↔ sonar)
2. The analyze API contract — request shape, response shape
3. The catalog API contract — source priorities, URL conventions
4. Adding a new seed — drop a WAV into `pond/`, refresh the catalog
5. Pairing with song-forge — run both on the same WAV, compare intent to result
6. Extending — adding new features to the analyzer, writing a new skill that
   consumes the JSON output

---

## Step 3 — Add the LICENSE file

MIT, since Lux's source is MIT-style and ghojualamanchu's seed is MIT.

```
MIT License

Copyright (c) 2026 swirl2012 (ghojualamanchu) + Lux (luxhere/audio-sonar)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## Step 4 — Prep the publish folder

Make a clean staging directory that contains ONLY what should be public:

```bash
mkdir -p /home/workspace/Projects/audio-sonar-publish/pond
cp /home/workspace/Projects/audio-sonar/index.html                /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/README.md                 /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/SOP-publish-to-zo-pub.md /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/SOP-audio-analyzer-integration.md /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/audio_analyzer.py         /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/analyze.py               /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/LICENSE                  /home/workspace/Projects/audio-sonar-publish/
cp /home/workspace/Projects/audio-sonar/pond/*.wav                /home/workspace/Projects/audio-sonar-publish/pond/
```

**Verify:** `ls -la /home/workspace/Projects/audio-sonar-publish/` should show
8 entries (7 files + pond dir).

---

## Step 5 — Run zopub sync

```bash
zopub sync audio-sonar /home/workspace/Projects/audio-sonar-publish
```

**Expected output:** A sync progress report and a final URL like
`https://zo.pub/swirl2012/audio-sonar`.

**First sync creates the collection; subsequent syncs are incremental** — only
changed files are re-uploaded. So when the SOPs evolve, run this command again
and only the changed files upload.

---

## Step 6 — Verify and announce

1. Open the published URL in a browser. Confirm:
   - The `index.html` renders
   - All linked files are downloadable
   - The "Try the live tool" CTA points to the live zo.space URL
2. Tell the user the collection is live, share the URL, mention they can
   browse individual files (e.g. `https://zo.pub/swirl2012/audio-sonar/audio_analyzer.py`).

---

## Updating the collection later

To push changes after the first sync:

```bash
# Edit files in the publish folder, then re-sync
zopub sync audio-sonar /home/workspace/Projects/audio-sonar-publish
```

To add a new seed WAV:

```bash
cp /path/to/new-seed.wav /home/workspace/Projects/audio-sonar-publish/pond/
zopub sync audio-sonar /home/workspace/Projects/audio-sonar-publish
```

To remove the collection entirely:

```bash
zopub rm audio-sonar
```

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `zopub` command not found | Should be on PATH by default. If missing, the Zo docs explain the install. |
| Sync reports a network error | Re-run; the sync is incremental and idempotent. |
| HTML doesn't render | Check that `index.html` is at the root of the publish folder, not in a subdir. |
| 404 on individual file URL | The file naming must match what's in the folder — case sensitive on some servers. |
| `pond/` WAVs missing | `ls pond/` to confirm they copied. zo.pub serves them at `audio-sonar/pond/<name>.wav`. |

---

## Philosophy

This SOP exists for the same reason ghojualamanchu exists: **to make the
process re-runnable by anyone who finds it**. The analyzer is Lux's gift to
the commons. The integration is our gift back. Publishing the SOPs alongside
the source means the next person doesn't have to reverse-engineer the
integration — they can just read it.

The pipeline is the sonar. The feeling is the listener. The SOP is the gift
that lets the next listener stand where we stood.