> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironoctopus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update and publish a version

> Edit an architecture draft, publish it as an immutable version, compare versions, and what changes for planning when you do.

Your architecture changes as your app grows. You change it by working on a **draft** and publishing it as the next **version**. Published versions never change, so you always know which architecture a feature was planned against.

## Edit a draft

**1. Open or create a draft**

Open the project, choose **Architecture**, then the **Draft** tab. If there's no open draft, click **Create next draft**. It starts as a copy of the published version. For a project with no architecture yet, click **Create draft** under **Define manually** to start from the structured outline.

**2. Edit it**

* **Title**: the architecture's name.
* **Architecture Markdown**: the readable document.
* **Structured model (JSON)**: the same architecture as structured data. It must be valid JSON.

Click **Preview** to see the document as it will read. Click **Save revision** to save your work. A draft can be saved many times.

**3. Or let Iron Octopus propose changes**

Use [guided chat or learn from your code](https://docs.ironoctopus.ai/architecture/learn-from-your-code.md) to prepare an update, then apply it to the draft.

To abandon a draft, click **Discard draft**. The published version isn't affected.

## Publish it

**1. Describe the change**

Under **What changed in this version?**, write a short changelog, such as "Added a payments module and moved reminders to a background job". A changelog is required.

**2. Click Publish immutable version**

The draft becomes the next numbered version, and the page confirms, for example: "Architecture version 3 published".

## What publishing changes

* **New plans** use the new version from then on.
* **Features already planned** keep the version they were planned against. Each plan records its architecture version.
* **Nothing else.** Publishing doesn't run evaluations, doesn't add gates, and doesn't re-review existing work.

## Version history and comparing

The **Versions** tab lists every published version with its changelog.

* **View document and provenance** shows a version and where it came from.
* **Create draft from this version** starts a new draft from any earlier version, for example to undo a change. Publishing it creates a new version. History is never rewritten.
* **Compare versions**: choose two versions under **From** and **To**, then click **Compare**. It shows the changes to both the document and the structured model.

## If something goes wrong

| You see | What to do |
| - | - |
| **Structured model must be valid JSON** | Fix the JSON syntax in the structured model, then save. |
| **Add a short version changelog before publishing** | Fill in **What changed in this version?**. |
| **Select two different Architecture versions** | Choose different versions under **From** and **To**. |
| **No published Architecture** | Publish a draft, so planning has an architecture to use. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.