diff --git a/docs/docs/GitW3/_category_.json b/docs/docs/GitW3/_category_.json
new file mode 100644
index 000000000..793bc9380
--- /dev/null
+++ b/docs/docs/GitW3/_category_.json
@@ -0,0 +1,8 @@
+{
+    "label": "GitW3",
+    "position": 1.5,
+    "link": {
+        "type": "generated-index",
+        "description": "Sign in, create or port a W3DS platform, publish releases, apply for PPA, and register deployments with GitW3."
+    }
+}
diff --git a/docs/docs/GitW3/create-a-platform.md b/docs/docs/GitW3/create-a-platform.md
new file mode 100644
index 000000000..ff4ffc61e
--- /dev/null
+++ b/docs/docs/GitW3/create-a-platform.md
@@ -0,0 +1,79 @@
+---
+sidebar_position: 3
+title: Create a new platform
+description: Create a repository, initial W3DS manifest, and permanent platform identity with GitW3.
+---
+
+# Create a new platform
+
+Use **Make a new platform** when the application does not already have a W3DS platform identity. GitW3 creates the repository and initial manifest, then provisions the permanent platform eName asynchronously.
+
+From the **+** menu, select **New repository**, then choose **Make a new platform**.
+
+![The GitW3 choice between making a new platform and porting an existing application.](/img/gitw3/choose-platform-path.png)
+
+## Step 1: Repository
+
+Choose the owner and describe where the code will live:
+
+1. Select your user or an organization as **Owner**.
+2. Decide whether the repository is private.
+3. Enter the human-facing **Display name**.
+4. Confirm the default branch, normally `main`.
+
+![Step one of the create-platform wizard, where the owner and display name are selected.](/img/gitw3/new-platform-repository.png)
+
+You do not choose a repository slug. GitW3 derives a URL-safe repository name and the initial stable `platformName` from the display name. If that name is already used under the owner, GitW3 adds a numeric suffix safely.
+
+The display name can change later. Treat `platformName` as the permanent machine-facing identity; GitW3 will not change it when the friendly name changes.
+
+## Step 2: Platform details
+
+Enter the information W3DS needs to describe the platform:
+
+- **Description:** a concise explanation of what the platform does;
+- **Application domains:** one or more domains from the W3DS ontology;
+- **Application URL:** the public URL, if the application is already deployed; and
+- **Logo URL:** an optional public image URL.
+
+![Step two of the create-platform wizard, with a description, W3DS domains, application URL, and logo URL.](/img/gitw3/new-platform-details.png)
+
+The version is controlled by Git releases, not entered in this form. The initial version is `0.1.0` until a stable semantic release becomes the repository's published version.
+
+You can leave the application URL empty while building. It is required before applying for PPA.
+
+## Step 3: AI setup
+
+Choose whether GitW3 should show the quick install for the W3DS coding-agent skill.
+
+![Step three of the create-platform wizard, offering the W3DS skill command for supported coding agents.](/img/gitw3/new-platform-ai-setup.png)
+
+The command works with supported agents including Codex, Claude Code, Cursor, Copilot, and Windsurf:
+
+```bash
+npx skills add MetaState-Prototype-Project/prototype@w3ds
+```
+
+Select **Create platform**. GitW3 creates:
+
+- the repository;
+- an initial README;
+- `.w3ds/platform.json`; and
+- the first commit on the default branch.
+
+It does not create or expose a reusable platform private key. The permanent platform identity and its eVault are provisioned automatically without an application or deployment key.
+
+## After creation
+
+The welcome page shows the permanent eName as soon as publication completes. Keep the page open or return to the **W3DS** tab later; provisioning continues in the background.
+
+Next:
+
+1. Clone the repository and push the application code.
+2. Open the **W3DS** tab and confirm the manifest and identity status.
+3. Add the public application URL when the deployment is reachable.
+4. Publish a stable semantic release such as `v0.1.0`.
+5. Apply for a PPA certificate for that exact version.
+6. Register a deployment from the **Deploy** tab.
+
+See [The platform manifest and W3DS workspace](./platform-manifest-and-workspace) for the generated file and editable fields.
diff --git a/docs/docs/GitW3/deploy-a-release.md b/docs/docs/GitW3/deploy-a-release.md
new file mode 100644
index 000000000..7147311c5
--- /dev/null
+++ b/docs/docs/GitW3/deploy-a-release.md
@@ -0,0 +1,99 @@
+---
+sidebar_position: 8
+title: Register a deployment
+description: Create and sign a verifiable W3DS deployment record for a PPA-certified release.
+---
+
+# Register a deployment
+
+The GitW3 **Deploy** tab registers a verifiable W3DS deployment identity for a published release. It binds the exact code version, deployment environment, connected deployer, and a public application key.
+
+:::important
+
+This flow does not upload or run the application. Deploy the code with your normal hosting provider or pipeline, then use the generated key in that server or runtime when PP-Auth integration is available.
+
+:::
+
+## Prerequisites
+
+Before starting, confirm:
+
+- the platform eName is ready;
+- a stable semantic release is published;
+- PPA has granted a certificate for that exact version;
+- you are signed in with the eID wallet that will act as the deployer; and
+- the W3DS deployment publisher is available.
+
+Every deployment belongs to the connected deployer's eName. It does not claim that the platform authors or release committers operated the deployment.
+
+## Step 1: Choose release
+
+Open **Deploy** and select a PPA-certified release. The release binds the version tag and exact commit to the stable platform eName. Uncertified releases remain unavailable.
+
+You can register additional versions later without replacing earlier records.
+
+## Step 2: Describe deployment
+
+Enter a human-friendly name such as `Singapore production`, then choose an environment:
+
+- Production
+- Staging
+- Development
+- Custom
+
+These values distinguish multiple deployments of the same release. They do not configure a hosting region, DNS record, or deployment pipeline.
+
+## Step 3: Bind an application key
+
+Choose one of two key paths:
+
+### Generate a deployment key
+
+This is recommended for a first deployment. GitW3 generates an ECDSA P-256 key pair in the browser and downloads `w3ds-deployment-key.json` immediately. The backup uses the `w3ds-deployment-key-v1` format and contains:
+
+- algorithm metadata for ECDSA P-256 with SHA-256;
+- the `z`-prefixed public key;
+- the base64-encoded PKCS#8 private key; and
+- a creation timestamp.
+
+Confirm that the file was downloaded and stored safely before continuing.
+
+### Use an existing public key
+
+Choose this path when your runtime or secret manager already controls a compatible W3DS P-256 key. Paste only the `z`-prefixed public key. Do not upload or paste the private key into GitW3.
+
+:::danger The private key is shown only through the download
+
+GitW3 receives the public key and cannot recover the private key. Never commit `w3ds-deployment-key.json`, paste it into chat, expose it through an API, or ship it in a browser or mobile bundle.
+
+:::
+
+Store the private file in the hosting provider's secret manager or a read-only server mount. Prefer an environment variable such as `W3DS_DEPLOYMENT_KEY_FILE` that points to the mounted file instead of putting key material in an environment variable.
+
+## Step 4: Review and sign
+
+Review the release, deployment name, environment, deployer identity, and key handling confirmation. GitW3 reserves two identities:
+
+- a **deployment eName** bound to the deployment's public key and connected deployer; and
+- a **software-version eName** bound to the stable platform eName, release version, and exact Git commit.
+
+Select **Create identities and continue to wallet**, then scan or open the eID wallet. One wallet signature covers both documents. Nothing is provisioned until the signature is verified.
+
+## Publication and server integration
+
+The deployment card progresses through publishing, waiting for W3DS, published, or needs-attention states. After publication it shows both eNames and a **Use AI to configure the server** helper.
+
+That generated prompt contains the verified public deployment context but not the private key. It asks a coding assistant to:
+
+- inspect the existing server runtime and deployment method;
+- add a server-only loader for `w3ds-deployment-key-v1`;
+- validate P-256/SHA-256 and ensure the private key derives the expected public key;
+- keep key loading unreachable from client code;
+- use a secret manager or read-only mount; and
+- leave a narrow PP-Auth integration boundary without inventing an unpublished SDK or protocol.
+
+Keep the downloaded private-key file local when using that prompt. PP-Auth SDK integration is marked as coming soon in GitW3; do not invent a package name, endpoint, token format, or wire protocol.
+
+## Rotation and recovery
+
+If the private key is lost, GitW3 cannot restore it. Register a new deployment identity and update the server secret through a controlled rollout. Keep the old secret available only for the rollback window, verify the new public-key match at startup, then revoke or destroy the old secret according to your hosting policy.
diff --git a/docs/docs/GitW3/overview.md b/docs/docs/GitW3/overview.md
new file mode 100644
index 000000000..e6fe9f313
--- /dev/null
+++ b/docs/docs/GitW3/overview.md
@@ -0,0 +1,70 @@
+---
+sidebar_position: 1
+title: GitW3 overview
+description: Start here to understand GitW3 repositories, W3DS identities, releases, certification, and deployment records.
+---
+
+# GitW3 overview
+
+[GitW3](https://git.w3ds.metastate.foundation) is the W3DS-aware Git forge. It hosts source code and normal collaborative Git workflows, while connecting a platform repository to its permanent W3DS identity, published versions, PPA certificates, and verifiable deployment records.
+
+GitW3 is built around one rule: the repository is the source of truth for the platform metadata that W3DS publishes. The metadata lives beside the code in `.w3ds/platform.json`, and changes made from the GitW3 **W3DS** tab become ordinary commits on the default branch.
+
+## What GitW3 manages
+
+| Item | Meaning | Where you work with it |
+| --- | --- | --- |
+| Repository | Source code, issues, pull requests, tags, and releases | The regular repository tabs and Git |
+| Platform manifest | Version-controlled W3DS metadata | `.w3ds/platform.json` and the **W3DS** tab |
+| Platform eName | The permanent identity of the platform across releases | Provisioned automatically and shown on the **W3DS** tab |
+| Version eName | The identity of one exact released version | Derived from a stable Git release |
+| PPA certificate | Approval for one exact platform version | Apply and follow the review from the **W3DS** tab |
+| Deployment eName | A verifiable record of one running deployment | Created from the **Deploy** tab |
+
+The platform eName remains stable when the code, release, or deployment changes. Each released software version and each deployment receives its own identity so that W3DS records can refer to an exact artifact or running instance.
+
+:::important GitW3 records deployments; it does not host them
+
+The **Deploy** flow creates W3DS identities and attestations. Continue using your normal hosting provider or deployment pipeline to run the application.
+
+:::
+
+## The normal platform lifecycle
+
+```mermaid
+flowchart LR
+    A[Sign in with W3DS] --> B[Create or port a repository]
+    B --> C[Platform manifest committed]
+    C --> D[Permanent platform eName provisioned]
+    D --> E[Publish a stable release]
+    E --> F[Sign and submit PPA application]
+    F --> G[PPA certificate granted]
+    G --> H[Register and sign a deployment]
+```
+
+Identity and profile publication happen asynchronously. Git pushes and repository creation do not wait synchronously for every W3DS service. The status shown on the **W3DS** tab updates as the publisher completes or retries the work.
+
+## Choose the right starting path
+
+- **Make a new platform** creates a repository, an initial README, and `.w3ds/platform.json`. Use it when the application does not already have a W3DS identity.
+- **Port an existing app** creates an empty destination first. You then move the existing Git history and W3DS integration, transfer an existing eName if there is one, and explicitly activate the public cutover.
+- A regular code import is not the same as porting a W3DS platform. Use the guided port flow when an existing platform identity must remain intact.
+
+Continue with [Sign in and manage your account](./sign-in-and-account), [Create a new platform](./create-a-platform), or [Port an existing application](./port-an-existing-application).
+
+## Before you begin
+
+You need:
+
+- an eID wallet with a W3DS identity;
+- Git installed locally if you will clone or push code;
+- an SSH key or a GitW3 personal access token for command-line Git authentication; and
+- repository owner or organization permissions for actions such as PPA submission and migration activation.
+
+For application integration work, GitW3 can give a supported coding agent the current W3DS skill:
+
+```bash
+npx skills add MetaState-Prototype-Project/prototype@w3ds
+```
+
+The skill helps the agent use current protocol concepts and ontology identifiers. It does not replace review, tests, or secret handling.
diff --git a/docs/docs/GitW3/platform-manifest-and-workspace.md b/docs/docs/GitW3/platform-manifest-and-workspace.md
new file mode 100644
index 000000000..740f27f9e
--- /dev/null
+++ b/docs/docs/GitW3/platform-manifest-and-workspace.md
@@ -0,0 +1,94 @@
+---
+sidebar_position: 6
+title: Platform manifest and W3DS workspace
+description: Understand .w3ds/platform.json, asynchronous publication, visibility, and the repository W3DS tab.
+---
+
+# Platform manifest and W3DS workspace
+
+Every GitW3 platform repository owns a manifest at `.w3ds/platform.json`. It is version-controlled platform metadata and the source from which GitW3 publishes the platform profile to W3DS.
+
+## Manifest shape
+
+A newly created platform starts with the following core fields:
+
+```json
+{
+  "schemaVersion": 1,
+  "platformName": "example-platform",
+  "displayName": "Example Platform",
+  "description": "A short description of the platform.",
+  "version": "0.1.0",
+  "ename": null,
+  "url": "https://example.invalid",
+  "logoUrl": "https://example.invalid/logo.png",
+  "domains": ["productivity", "work"],
+  "inSubmission": false,
+  "submissionVersion": "",
+  "isDraft": true
+}
+```
+
+Use real W3DS ontology domain identifiers from the GitW3 selector. The values above are illustrative.
+
+## Who controls each field
+
+| Field | Control and behavior |
+| --- | --- |
+| `schemaVersion` | Manifest format version. Do not change it without a supported schema migration. |
+| `platformName` | Stable machine-facing platform slug derived at creation. Immutable after identity creation. |
+| `displayName` | Human-facing name. Editable by permitted repository users. |
+| `description` | Human-facing platform description. |
+| `version` | Synchronized from the latest stable semantic GitW3 release; do not manually bump it. |
+| `ename` | Permanent platform eName. Initially `null`, then written by the publisher or preserved by the port flow. Immutable once assigned. |
+| `url` | Public application URL. Required for PPA submission. |
+| `logoUrl` | Optional public logo URL. |
+| `domains` | One or more supported W3DS application-domain identifiers. |
+| `inSubmission` | Whether the current release statement is in the PPA review flow. Managed by the signed application workflow. |
+| `submissionVersion` | Version associated with the current signed PPA submission. |
+| `isDraft` | Controls whether the synchronized platform profile is hidden from the public marketplace. |
+
+Migration and PPA workflows can add proof fields. Never fabricate, copy between platforms, or hand-edit cryptographic proof material.
+
+## The W3DS workspace
+
+Open a platform repository and select **W3DS**. The page is organized around the platform lifecycle:
+
+1. **Live publication status** reports the publisher's current state and latest result.
+2. **What happens next** tracks manifest, permanent identity, application URL, and stable release readiness.
+3. **Marketplace visibility** switches the profile between draft and published.
+4. **Platform details** edits the display name, description, domains, application URL, and logo URL.
+5. **PPA certificate** shows the requirement checklist, signed application, review conversation, and current decision.
+
+Repository or organization permissions control who may edit details, change visibility, apply for PPA, or activate a migration. Read-only visitors see the manifest-backed values without the edit controls.
+
+## Saving changes
+
+Saving through the W3DS workspace creates a normal commit on the default branch. GitW3 checks the last observed commit so it does not silently overwrite a newer manifest change.
+
+For changes made locally:
+
+1. Pull the latest default branch.
+2. Edit only supported, non-managed fields.
+3. Validate the JSON and domain identifiers.
+4. Commit and push normally.
+5. Open the **W3DS** tab and watch publication status.
+
+Do not manually change `platformName`, an assigned `ename`, release-controlled `version`, or signed proof fields.
+
+## Identity and publication are asynchronous
+
+After the initial manifest reaches the default branch, GitW3's publisher:
+
+- reserves and publishes the permanent platform eName;
+- provisions the platform eVault without an application key;
+- writes the assigned eName back to the manifest; and
+- synchronizes the platform profile and its visibility.
+
+Repository creation and Git pushes remain available while this happens. Temporary W3DS failures are retried; refresh the **W3DS** tab to see the current state. Repository administrators can see a detailed last error when intervention is required.
+
+The platform eName gets the platform eVault. Version eNames are Registry records for exact releases and do not create additional eVaults.
+
+## Draft versus published
+
+New platforms begin as drafts. A synchronized draft profile is hidden from the marketplace but still belongs to the repository. Use **Publish platform** in the W3DS workspace when the profile is ready to be discoverable; use **Make draft** to hide it again without deleting its stable identity.
diff --git a/docs/docs/GitW3/port-an-existing-application.md b/docs/docs/GitW3/port-an-existing-application.md
new file mode 100644
index 000000000..979c38d73
--- /dev/null
+++ b/docs/docs/GitW3/port-an-existing-application.md
@@ -0,0 +1,126 @@
+---
+sidebar_position: 4
+title: Port an existing application
+description: Move an existing Git application and, when present, its W3DS eName into GitW3 without an early public cutover.
+---
+
+# Port an existing application
+
+The guided port flow separates moving code from transferring a live W3DS identity. It creates an empty destination first, lets you integrate and push safely, stages any existing eName migration, and changes the public platform only when an administrator explicitly activates the cutover.
+
+Use this path for an existing application, especially when it already has `.w3ds` configuration or a permanent platform eName. Do not use the generic repository import flow as a substitute for the guided W3DS port.
+
+## Create the destination
+
+From **New repository**, choose **Port an existing app**.
+
+1. Select the destination owner.
+2. Choose whether the new repository is private.
+3. Enter the application's display name.
+4. Confirm the destination default branch.
+5. Select **Create destination repository**.
+
+![The initial GitW3 form for creating an empty destination for an existing application.](/img/gitw3/port-existing-application.png)
+
+GitW3 generates the repository slug from the display name. At this point it creates only an empty destination: it does not pull, modify, or publish the existing application.
+
+The handoff page remains available at:
+
+```text
+https://git.w3ds.metastate.foundation/<owner>/<repository>/onboarding/port
+```
+
+You can leave and return to that URL at any time.
+
+## Step 1: Push the application
+
+The first handoff step shows the repository's exact HTTP and SSH remotes and a **Copy migration prompt** button. Give that prompt to a coding agent from inside the application's existing local Git checkout.
+
+The generated prompt tells the agent to:
+
+- inspect the existing branch, remotes, `.w3ds` directory, and eName before editing;
+- install the current W3DS skill;
+- preserve the application's behavior and complete Git history;
+- create a manifest only when no W3DS identity already exists;
+- preserve any existing eName exactly;
+- rename an existing `origin` to the first available upstream-style name;
+- set GitW3 as the new `origin`;
+- run relevant checks; and
+- push the current `HEAD` to the GitW3 default branch without rewriting history.
+
+The prompt contains repository coordinates only. It never contains the application token or another credential.
+
+### Move the history manually
+
+If the existing checkout already has an `origin`, preserve it first:
+
+```bash
+git remote -v
+git remote rename origin upstream
+git remote add origin https://git.w3ds.metastate.foundation/<owner>/<repository>.git
+git push -u origin HEAD:main
+```
+
+If `upstream` is already used, choose `upstream-2` or another unused name. If there is no `origin`, skip the rename. Copy the real URL and default branch from the handoff page rather than typing them from memory.
+
+Before pushing, ensure one of these states is true:
+
+- **New to W3DS:** a valid `.w3ds/platform.json` exists with `ename` set to `null`.
+- **Existing W3DS platform:** the existing `.w3ds` content and eName remain intact.
+
+Never invent an eName, token, migration proof, ontology identifier, endpoint, or credential. Never force-push unless you have independently reviewed and approved the history rewrite.
+
+After the default branch contains application code, return to the handoff and select **Check for pushed code**. GitW3 then unlocks step 2.
+
+## Step 2: Migrate the existing eName
+
+Skip this transfer when the application has no existing eName; continue to the repository's **W3DS** tab with the unclaimed manifest from step 1.
+
+When an existing permanent eName is present:
+
+1. Enter that platform eName and its current platform token.
+2. Select **Review and sign migration**.
+3. Review the source platform and exact destination repository in the connected eID wallet.
+4. Approve the signed transfer statement.
+
+GitW3 checks that:
+
+- the token resolves exactly one valid `PlatformProfile` for that eName;
+- the connected wallet is an author of the platform profile;
+- the destination manifest is readable; and
+- the manifest does not already contain a conflicting identity.
+
+The raw token is sent to W3DS for validation and is not stored by GitW3. GitW3 retains only a one-way fingerprint, so you will need the original token again for final activation.
+
+After the wallet signature is verified, GitW3 commits the staged migration proof to the repository. The live public platform still has not changed.
+
+:::note Legacy profiles without authors
+
+If an older profile names no human authors, the signed migration enters an administrator review queue. Approval stages the repository but still does not activate the public cutover.
+
+:::
+
+## Step 3: Activate the public cutover
+
+Before activation:
+
+1. Review the staged identity and repository manifest.
+2. Confirm the complete application is on the default branch.
+3. Publish the required stable release and ensure its version matches the manifest.
+4. Open the repository's **W3DS** tab as a repository or organization administrator.
+5. Re-enter the exact original platform token.
+6. Select **Activate migration** and confirm the irreversible management transfer.
+
+Activation revokes the original token for `PlatformProfile` writes and transfers live management to this GitW3 repository. Until that final action succeeds, the old public listing remains in control.
+
+## Stop instead of guessing when
+
+- authentication to either remote fails;
+- the GitW3 destination is unexpectedly non-empty;
+- local and destination histories conflict;
+- an existing eName would be removed or replaced;
+- `.w3ds/platform.json` is invalid;
+- the connected wallet is not an author of the existing profile; or
+- a push would require rewriting history.
+
+Fix the underlying issue, then return to the same handoff URL. The flow is designed to be resumed later.
diff --git a/docs/docs/GitW3/releases-and-ppa.md b/docs/docs/GitW3/releases-and-ppa.md
new file mode 100644
index 000000000..16cb1d8be
--- /dev/null
+++ b/docs/docs/GitW3/releases-and-ppa.md
@@ -0,0 +1,78 @@
+---
+sidebar_position: 7
+title: Releases and PPA certification
+description: Publish an exact semantic version, sign its PPA application, and follow version-scoped review decisions.
+---
+
+# Releases and PPA certification
+
+PPA certification applies to one exact released version of a platform. Publishing new code or a new version does not inherit the previous version's certificate.
+
+## Prepare the platform
+
+The **PPA certificate** section on the repository's **W3DS** tab shows a checklist. Before an application can be signed, the repository needs:
+
+- a ready permanent W3DS platform identity;
+- at least one supported application domain;
+- a public application URL;
+- a published stable semantic Git release; and
+- a repository or organization owner/admin signed in with an eID wallet.
+
+## Publish the release
+
+1. Merge and test the exact commit you intend to release.
+2. Create a semantic version tag such as `v1.2.3`.
+3. Push the tag to GitW3.
+4. Open **Releases → New release**.
+5. Select the tag, write release notes, leave it as a stable release, and publish.
+
+GitW3 normalizes `v1.2.3` to platform version `1.2.3`, binds the version to the release commit, derives its version eName, and synchronizes the manifest. Wait for the **W3DS** tab to report the release as ready before applying.
+
+Avoid mutable or ambiguous release tags. A draft, prerelease, or non-semantic tag such as `latest` does not become the W3DS platform version.
+
+## Sign and submit the PPA application
+
+Only a repository or organization owner/admin can submit the release.
+
+1. Open the repository's **W3DS** tab.
+2. Review every PPA checklist item and the exact version shown.
+3. Select **Sign and apply for PPA certificate**.
+4. Scan the QR code or open the connected eID wallet.
+5. Review the release statement as your displayed eName.
+6. Approve it and keep the dialog open until GitW3 verifies the signature.
+
+The signing request is one-time and expires after 15 minutes. GitW3 validates the connected wallet's Registry certificate and P-256 signature. When verification succeeds, it commits the submission proof with `inSubmission: true` and stores the signed platform profile in the platform eVault.
+
+Never invent or manually paste a submission proof into the manifest.
+
+## Follow the review
+
+The PPA area records the conversation for the current version, including:
+
+- the original signed application;
+- the signing actor and recorded time;
+- the submitted, granted, or denied state;
+- a reviewer reason when one was published; and
+- signed responses and reapplications.
+
+Possible states are:
+
+| State | Meaning |
+| --- | --- |
+| Ready to apply | All prerequisites are satisfied and the version has no active decision. |
+| Application submitted | The signed statement is stored and waiting in the PPA review queue. |
+| PPA certificate granted | That exact version may be used in the GitW3 deployment flow. |
+| PPA application denied | Address the decision and submit a signed response if reapplying. |
+
+After a denial, enter a concise response explaining what changed or why the version should be reconsidered, then select **Sign and reapply**. The response becomes part of the next signed release statement and review history.
+
+## Release a new version
+
+For `v1.2.4` or any later version:
+
+1. Publish a new stable release.
+2. Wait for the manifest and version eName to synchronize.
+3. Review the PPA checklist for the new version.
+4. Sign and submit a new application.
+
+The certificate for `1.2.3` remains a record for `1.2.3`; it does not certify `1.2.4`. The **Deploy** tab only enables releases for which PPA granted a certificate for the exact normalized version.
diff --git a/docs/docs/GitW3/sign-in-and-account.md b/docs/docs/GitW3/sign-in-and-account.md
new file mode 100644
index 000000000..0b23442d6
--- /dev/null
+++ b/docs/docs/GitW3/sign-in-and-account.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 2
+title: Sign in and manage your account
+description: Use an eID wallet to sign in to GitW3 and understand W3DS usernames and profile data.
+---
+
+# Sign in and manage your account
+
+GitW3 web access uses **Sign in with W3DS**. There is no username-and-password web login for users.
+
+1. Open [git.w3ds.metastate.foundation](https://git.w3ds.metastate.foundation).
+2. Select **Sign in with W3DS**.
+3. Scan the QR code with your eID wallet, or select **Open your wallet** when the wallet is on the same device.
+4. Review and approve the sign-in request in the wallet.
+5. Keep the browser page open until GitW3 completes the redirect.
+
+![The GitW3 Sign in with W3DS page, with a wallet QR code and an Open your wallet button.](/img/gitw3/sign-in-with-w3ds.png)
+
+The QR code is a short-lived request. Reload the page and start again if it expires.
+
+## Your GitW3 identity
+
+Your GitW3 username is derived from your W3DS eName. GitW3 displays a cosmetic `@` in front of user and organization names to make their identity clear.
+
+:::note The `@` is presentation only
+
+Do not add or remove characters in a clone URL. Copy the exact HTTP or SSH URL shown by the repository. Internally, GitW3 uses the owner name without the cosmetic `@` in URL paths and Git coordinates.
+
+:::
+
+At sign-in, GitW3 also makes a best-effort lookup of the newest person profile in Awareness-as-a-Service (AaaS):
+
+- the AaaS `displayName` or equivalent name becomes the friendly display name;
+- the AaaS avatar becomes the account avatar when it is a valid permitted HTTP(S) image; and
+- if AaaS is unavailable, sign-in still succeeds and the existing or wallet-provided profile remains in place.
+
+Because profile enrichment happens during sign-in, sign out and sign in again after changing your W3DS person profile if GitW3 still shows the previous name or avatar.
+
+## Browser sign-in versus Git authentication
+
+The wallet signs you into the website, but command-line Git needs its own credential:
+
+- **SSH:** add your public key under **User settings → SSH / GPG Keys**, then use the SSH clone URL. This is the recommended day-to-day setup.
+- **HTTPS:** create a personal access token under **User settings → Applications** and use it as the password when Git prompts. Do not use a wallet secret or try to invent a GitW3 password.
+
+Treat a personal access token like a password. Give it only the permissions required for the task, store it in a credential manager, and revoke it if exposed.
+
+## Sign-in troubleshooting
+
+- **The wallet did not open:** scan the QR code instead, or make sure the wallet is registered as the handler for its link type.
+- **The QR code expired:** reload the sign-in page and approve the new request.
+- **The approval finished but the browser did not move:** keep the original tab open, then retry once with a fresh request.
+- **The displayed name or avatar is old:** sign out and back in to trigger AaaS enrichment again.
+- **`git push` asks for a password:** the browser session is not a Git credential. Configure SSH or use a personal access token over HTTPS.
diff --git a/docs/docs/GitW3/troubleshooting.md b/docs/docs/GitW3/troubleshooting.md
new file mode 100644
index 000000000..ecdd40cf7
--- /dev/null
+++ b/docs/docs/GitW3/troubleshooting.md
@@ -0,0 +1,129 @@
+---
+sidebar_position: 9
+title: Troubleshooting GitW3
+description: Diagnose sign-in, Git authentication, manifest publication, porting, PPA, and deployment problems safely.
+---
+
+# Troubleshooting GitW3
+
+Start with the repository's **W3DS** tab. It reads current W3DS publication state whenever the page loads, and repository administrators can see the publisher's detailed last error.
+
+## Sign-in and profile
+
+### The wallet QR expired
+
+Reload the sign-in page and approve a new request. Wallet sign-in requests are intentionally short-lived.
+
+### The name or avatar is stale
+
+GitW3 enriches the local account from the newest W3DS person profile in AaaS during sign-in. Sign out and sign in again. AaaS failure does not block authentication, so an older profile may remain during an outage.
+
+### A username-and-password form appears
+
+The production user login should offer **Sign in with W3DS**, not a local password form. Make sure you are using `https://git.w3ds.metastate.foundation/user/login` and report the page URL and time to the GitW3 operator. Do not enter a reused password into an unexpected form.
+
+## Clone and push
+
+### Browser sign-in works, but Git rejects credentials
+
+The browser wallet session does not authenticate command-line Git. Add an SSH key and use the SSH clone URL, or create a personal access token and use it as the HTTPS password.
+
+### The remote owner starts with `@`
+
+The UI `@` is cosmetic. Replace a hand-typed URL with the exact HTTP or SSH URL from the repository clone control.
+
+### Pushes go to the old provider
+
+Inspect remotes:
+
+```bash
+git remote -v
+```
+
+For a ported application, preserve the old remote under `upstream` and make the GitW3 URL `origin`. Return to the repository's `/onboarding/port` page for the exact generated instructions.
+
+## Manifest and identity publication
+
+### The platform eName is still pending
+
+Provisioning is asynchronous and GitW3 retries temporary W3DS failures. Confirm `.w3ds/platform.json` exists on the default branch, then refresh the **W3DS** tab. If the administrator view shows a persistent error, report that exact error without including secrets.
+
+### GitW3 says the manifest is invalid
+
+Validate that `.w3ds/platform.json` is well-formed JSON and contains the supported schema. Do not fix it by inventing an eName or proof. Compare the core fields with [Platform manifest and W3DS workspace](./platform-manifest-and-workspace), preserve any existing assigned identity, and push the correction to the default branch.
+
+### A W3DS workspace edit conflicts
+
+Another commit changed the default branch after the page loaded. Pull or reload, review the newer manifest, and apply the edit again. GitW3 deliberately refuses to overwrite the newer commit silently.
+
+### The marketplace listing is missing
+
+Check all three states:
+
+1. the permanent identity is ready;
+2. the profile synchronization completed; and
+3. `isDraft` is `false` through the **Publish platform** visibility control.
+
+A draft profile remains hidden even when its identity is ready.
+
+## Existing application port
+
+### eName migration says to push first
+
+The destination default branch has not received the application. Push the existing checkout, including a valid `.w3ds/platform.json`, then use **Check for pushed code** on the handoff page. Step 2 is intentionally locked until code exists.
+
+### The existing eName conflicts with the manifest
+
+Stop. GitW3 will not replace a different eName already present in the destination manifest. Verify that you selected the correct source application and destination repository before making any change.
+
+### The token is rejected
+
+Use the current raw token for the exact existing platform eName. GitW3 must find exactly one matching valid `PlatformProfile`, and the connected wallet must be named as an author. The token is not retained, so the same original value is required again during activation.
+
+### The wallet is not an author
+
+Sign in with an eID wallet named by the existing platform profile. For a legacy profile with no authors, complete the signed request and wait for site administrator review.
+
+### The migration is staged but the old listing is still live
+
+That is expected. Staging does not cut over the public platform. Publish the required stable release, then have a repository or organization administrator open **W3DS**, review the staged migration, re-enter the original token, and explicitly activate it.
+
+## Releases and PPA
+
+### The release requirement is not ready
+
+Publish a stable release with a semantic tag such as `v1.2.3`. Draft releases, prereleases, and non-semantic tags do not control the platform version. Wait for the publisher to synchronize the normalized version before applying.
+
+### The PPA button is disabled
+
+Check the on-page requirements: stable identity, domains, public application URL, stable release, owner/admin permissions, and a connected eID wallet. Every item must be ready for the exact current version.
+
+### The signing request expired
+
+Close the dialog and start a fresh application. Do not reuse a signing URL or attempt to construct a proof manually.
+
+### A prior version was granted, but deployment is disabled
+
+PPA decisions are version-scoped. Publish and obtain a certificate for the exact new version selected in the deployment wizard.
+
+## Deployment
+
+### No release can be selected
+
+Confirm that the release is stable, semantic, synchronized to the platform manifest, and granted a PPA certificate for that exact normalized version.
+
+### The downloaded deployment key is missing
+
+Do not continue under the assumption that GitW3 can recover it. Generate a new key before signing if the wizard is still open, or register a new deployment identity if the signed deployment has already been published.
+
+### Publication is waiting for W3DS
+
+Leave the deployment record intact and refresh later. GitW3 separates repository availability from W3DS publisher retries. If the status becomes **Needs attention**, report the displayed failure to the operator without sharing the private key.
+
+### The server key does not match the deployment
+
+Fail closed. Derive the public key from the PKCS#8 private key and compare it to the public key shown on the deployment record. Never work around a mismatch by changing the expected key in code; mount the correct secret or create a new deployment identity.
+
+## Information safe to include in a support report
+
+Include the repository path, page URL, approximate time, release tag, public eNames, public deployment key, displayed status, and a sanitized error message. Never include wallet secrets, personal access tokens, migration tokens, session cookies, or the contents of `w3ds-deployment-key.json`.
diff --git a/docs/docs/GitW3/work-with-repositories.md b/docs/docs/GitW3/work-with-repositories.md
new file mode 100644
index 000000000..e7b107f38
--- /dev/null
+++ b/docs/docs/GitW3/work-with-repositories.md
@@ -0,0 +1,107 @@
+---
+sidebar_position: 5
+title: Work with repositories
+description: Clone, push, collaborate, and publish releases in a GitW3 repository.
+---
+
+# Work with repositories
+
+A GitW3 repository supports the familiar Git forge workflow: clone, branch, commit, push, review pull requests, track issues, tag versions, and publish releases. Platform repositories add **W3DS** and **Deploy** tabs to that workflow.
+
+## Clone a repository
+
+Open the repository and copy the exact URL from its **HTTP** or **SSH** clone control.
+
+### SSH
+
+Add your public SSH key under **User settings → SSH / GPG Keys**, then:
+
+```bash
+git clone <ssh-url-copied-from-gitw3>
+cd <repository-directory>
+```
+
+SSH is the easiest option for regular development because Git can authenticate with your local agent.
+
+### HTTPS
+
+Create a personal access token under **User settings → Applications**, then:
+
+```bash
+git clone <https-url-copied-from-gitw3>
+```
+
+When prompted, use your GitW3 account name as the username and the personal access token as the password. Store it in an operating-system credential manager rather than in a remote URL or shell script.
+
+The `@` displayed before eNames in the UI is cosmetic. Always use the owner and repository coordinates from the clone control exactly as shown.
+
+## Use an existing local checkout
+
+Inspect the current state before changing remotes:
+
+```bash
+git status
+git branch --show-current
+git remote -v
+```
+
+To preserve an old `origin` and make GitW3 the new one:
+
+```bash
+git remote rename origin upstream
+git remote add origin <clone-url-copied-from-gitw3>
+git push -u origin HEAD:main
+```
+
+Change `main` if the GitW3 repository uses another default branch. If this is an existing W3DS application, follow the complete [guided port flow](./port-an-existing-application) instead of treating the remote change as the entire migration.
+
+## Day-to-day collaboration
+
+A typical change uses a short-lived branch and a pull request:
+
+```bash
+git switch -c feat/my-change
+# edit and test
+git add <files>
+git commit -m "feat: describe the change"
+git push -u origin feat/my-change
+```
+
+Then open **Pull requests → New pull request**, choose the source and target branches, review the diff, and request review. Repository permissions and branch protection determine who can push or merge.
+
+Use:
+
+- **Issues** for bugs, tasks, and discussion;
+- **Pull requests** for reviewable branch changes;
+- **Actions** for configured automation and checks;
+- **Packages** for artifacts supported by the repository; and
+- **Releases** to publish stable platform versions.
+
+## Platform-specific tabs
+
+- **W3DS** shows live publication status, identity readiness, manifest details, visibility, PPA state, and any staged migration.
+- **Deploy** creates signed W3DS records for a PPA-certified release. It does not run the application's hosting pipeline.
+
+Edits made in the **W3DS** tab commit `.w3ds/platform.json` to the default branch. Pull before making related local changes so that you do not accidentally create competing manifest edits.
+
+## Publish a stable release
+
+GitW3 takes the platform version from the latest published stable release. Use a semantic version tag such as `v1.2.3`:
+
+```bash
+git switch main
+git pull --ff-only
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+```
+
+Then open **Releases → New release**, select the tag, add release notes, and publish it as a stable release. Drafts, prereleases, and non-semantic tags do not satisfy the W3DS stable-release requirement.
+
+GitW3 normalizes a leading `v`, so `v1.2.3` becomes manifest version `1.2.3`. See [Releases and PPA certification](./releases-and-ppa) before applying for certification.
+
+## Credentials and safe automation
+
+- Give personal access tokens the smallest useful scope and rotate them periodically.
+- Use deploy keys or a dedicated service identity for repository automation instead of a person's broad token where possible.
+- Never commit wallet secrets, migration tokens, personal access tokens, or `w3ds-deployment-key.json`.
+- Protect the default branch and require checks for repositories that publish production platforms.
diff --git a/docs/static/img/gitw3/choose-platform-path.png b/docs/static/img/gitw3/choose-platform-path.png
new file mode 100644
index 000000000..791317b43
Binary files /dev/null and b/docs/static/img/gitw3/choose-platform-path.png differ
diff --git a/docs/static/img/gitw3/new-platform-ai-setup.png b/docs/static/img/gitw3/new-platform-ai-setup.png
new file mode 100644
index 000000000..eb9931c78
Binary files /dev/null and b/docs/static/img/gitw3/new-platform-ai-setup.png differ
diff --git a/docs/static/img/gitw3/new-platform-details.png b/docs/static/img/gitw3/new-platform-details.png
new file mode 100644
index 000000000..dc707de9a
Binary files /dev/null and b/docs/static/img/gitw3/new-platform-details.png differ
diff --git a/docs/static/img/gitw3/new-platform-repository.png b/docs/static/img/gitw3/new-platform-repository.png
new file mode 100644
index 000000000..eca85ad0c
Binary files /dev/null and b/docs/static/img/gitw3/new-platform-repository.png differ
diff --git a/docs/static/img/gitw3/port-existing-application.png b/docs/static/img/gitw3/port-existing-application.png
new file mode 100644
index 000000000..d8cf521d6
Binary files /dev/null and b/docs/static/img/gitw3/port-existing-application.png differ
diff --git a/docs/static/img/gitw3/sign-in-with-w3ds.png b/docs/static/img/gitw3/sign-in-with-w3ds.png
new file mode 100644
index 000000000..44cbd7fb9
Binary files /dev/null and b/docs/static/img/gitw3/sign-in-with-w3ds.png differ