Refine docs IA and marketing homepage for lifecycle positioning

.github/workflows/platform-checks.yml

@@ -24,6 +24,11 @@ jobs:
       - name: Set up Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Install Linux DBus development package
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libdbus-1-dev
+
       - name: Test generated platform scripts
         run: cargo test -p fission-cli
 
@@ -41,6 +46,11 @@ jobs:
         with:
           targets: wasm32-unknown-unknown
 
+      - name: Install Linux DBus development package
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libdbus-1-dev
+
       - name: Check wasm core crates
         run: |
           cargo check -p fission-core --target wasm32-unknown-unknown
@@ -76,6 +86,11 @@ jobs:
         with:
           targets: aarch64-linux-android
 
+      - name: Install Linux DBus development package
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libdbus-1-dev
+
       - name: Set up Android SDK
         uses: android-actions/setup-android@v3
 

documentation/content/docs/build-and-package/overview.mdx

@@ -0,0 +1,40 @@
+---
+title: Build and package
+description: Package Fission apps for desktop, mobile, web, terminal, and static site targets with preflight checks and artifact manifests.
+---
+
+# Build and package
+
+Packaging turns a built app into an artifact another system can install, upload, host, or verify. Fission treats packaging as a first-class workflow because production releases fail when packaging is handled as a pile of shell scripts nobody understands.
+
+## Package outputs
+
+| Target | Package formats |
+| --- | --- |
+| Linux | `.run` |
+| macOS | `.app`, `.pkg` |
+| Windows | `.exe`, `.msi`, `.msix` |
+| Android | `.apk`, `.aab` |
+| iOS | `.ipa` |
+| Web/site | static HTML/CSS/JS asset directory or archive |
+
+Every package flow writes an `artifact-manifest.json` describing the output: project identity, target, format, profile, artifact paths, relative paths, file sizes, hashes, MIME types, and validation checks.
+
+## Preflight checks
+
+Run readiness checks before you package or release:
+
+```bash
+fission readiness package --project-dir . --target windows --format msix
+fission readiness release --project-dir . --target android --format aab --provider play-store
+```
+
+Readiness checks are deliberately concrete. They look for SDKs, NDKs, Xcode tools, Windows packaging tools, package scripts, signing tools, credentials, provider config, and artifact shape. The goal is to tell you what is missing before the release is blocked at the end of the process.
+
+## Signing
+
+Signing is platform-owned. Fission should orchestrate checks, configuration, and receipts, but it should use the tools provided by the platform owner for the part of the process they own. Signing secrets should come from environment variables, CI secret stores, authenticated platform tooling, or the Fission credential vault, not from plain text committed into `fission.toml`.
+
+## Where to go next
+
+Read [Production lifecycle](/product/production-lifecycle/) for the platform view and [Release and distribute](/docs/release-and-distribute/overview/) when you are ready to publish artifacts.

documentation/content/docs/develop/workflow.mdx

@@ -0,0 +1,38 @@
+---
+title: Develop workflow
+description: Use the Fission CLI, targets, shells, devices, logs, and project configuration during day-to-day app development.
+---
+
+# Develop workflow
+
+The Fission development workflow starts with one project and grows by adding targets. You do not create a separate product for every platform. You keep product behavior in shared Rust and let Fission generate or run the shell needed for the current target.
+
+## Daily loop
+
+1. Create or open a project with `fission.toml` at the root.
+2. Add the targets your product needs.
+3. Run the fastest target while building shared behavior.
+4. Switch to the real host whenever the question depends on browser, mobile, terminal, or static-site behavior.
+5. Keep logs attached while the app runs.
+6. Use readiness checks before packaging or publishing.
+
+```bash
+fission init my-app
+cargo fission add-target web android ios --project-dir my-app
+fission devices --project-dir my-app
+fission run --project-dir my-app
+```
+
+## Targets and shells
+
+A target is the output family you want to run or build. A shell is the host layer that boots the shared app model for that target. Desktop, web, mobile, terminal, and static site targets use different shell code, but the state, reducers, widgets, and design system stay shared.
+
+That distinction keeps your codebase maintainable. Product modules should not know whether they are inside a native window, browser, phone, terminal, or static page unless the feature itself depends on that host.
+
+## Configuration belongs in `fission.toml`
+
+`fission.toml` is the authoritative project root for targets, app metadata, site config, distribution config, release roots, and provider references. Keep long-form release notes, localized listing text, screenshots, and large provider metadata in referenced release-content files so the root manifest stays readable.
+
+## Where to go next
+
+Read [Platform shells, CLI, and testing](/docs/guides/platform-shells-cli-and-testing/) for the shell model, [Examples and targets](/docs/learn/examples-and-targets/) for target examples, and [Reference: CLI](/reference/cli/overview/) for command details.

documentation/content/docs/guides/platform-shells-cli-and-testing.mdx

@@ -5,9 +5,9 @@ description: Learn how Fission's shell wrappers and generated host projects fit
 
 # Platform shells, command-line interface, and testing
 
-Fission is suitable for production desktop, web, Android, and iOS apps today. The clearest way to understand that claim is to separate three different questions that often get mixed together.
+Fission is suitable for production desktop, web, Android, iOS, terminal, and static site work today. The clearest way to understand that claim is to separate three different questions that often get mixed together.
 
-The first question is whether the shared app model is ready for real product work. In Fission, that answer is yes. Your app state, actions, reducers, widgets, layout rules, semantics, and rendering model live in one shared runtime that is meant to power real desktop, browser, Android, and iOS applications.
+The first question is whether the shared app model is ready for real product work. In Fission, that answer is yes. Your app state, actions, reducers, widgets, layout rules, semantics, and rendering model live in one shared runtime that is meant to power real desktop, browser, mobile, terminal, and static site surfaces.
 
 The second question is whether every shell wrapper and every testing convenience is equally mature today. That answer is more nuanced. The shells expose slightly different wrapper methods, and the current live-testing hooks are not identical on every target.
 

documentation/content/docs/intro.mdx

@@ -1,34 +1,36 @@
 ---
 title: Docs
-sidebar_position: 1
-description: A gentle introduction to what Fission is, how it is structured, and what to read first.
+description: Follow the Fission software development lifecycle from setup through development, testing, packaging, signing, release, and distribution.
 ---
 
 # Docs
 
-If you are new to Fission, start here. Fission is a Rust framework for building user interfaces from one shared app model across desktop, web, Android, and iOS. These docs are written to help readers who may be new to Rust user interface work and even new to state-driven user interface, so the first goal is not to overwhelm you with names. The first goal is to give you a mental model that makes the rest of the framework feel understandable.
+Fission is a Rust application platform. It helps you build the app, run it on the targets your users care about, test and debug it, package it, sign it, prepare release content, and distribute it through stores, static hosts, GitHub Releases, object stores, and provider-specific tracks.
 
-Fission is structured around a simple idea: your app should behave predictably. In practice, that means the same app state, the same input, and the same time progression should lead to the same result. That kind of predictability matters because it makes bugs easier to reproduce, tests easier to trust, and cross-platform work easier to carry from one target to another without rewriting the core of the app.
+These docs are organized around that lifecycle. You can still learn individual concepts such as widgets, reducers, layout, charts, design systems, commands, jobs, and services, but the main path follows the way real software moves from an empty project to a released product.
 
-At a high level, a Fission app works like this. App state holds the data your product cares about, such as the current screen, the selected item, or the text in an editor. Actions are named messages that describe user intent, such as "increment the counter", "open this message", or "save the file". Reducers are the functions that receive those actions and change the state. Widgets then read the current state and describe the hierarchy of interface elements, sometimes called a widget tree, that should appear on screen right now. Finally, shells are the thin platform-specific runners that host the same shared app on desktop, web, Android, and iOS.
+## Recommended path
 
-This structure matters because it keeps each job in a clear place. State changes happen in one predictable path instead of being scattered through callbacks. Widgets focus on describing what to show instead of quietly performing outside work. Shells handle windows, browser surfaces, input, lifecycle, and accessibility, while the shared core still defines what the app means. The result is a framework that is easier to debug, easier to test, and easier to move across platforms.
+1. **Start** with [Quickstart](/docs/learn/quickstart/) and [Project structure](/docs/guides/app-structure/) so the repository shape and app model are clear.
+2. **Learn Fission** with [Runtime model](/docs/learn/runtime-model/), [Rendering pipeline](/docs/learn/rendering-pipeline/), [Layout and widgets](/docs/guides/layout-and-widgets/), and [Resources and async](/docs/guides/resources-and-async/).
+3. **Develop** with [Development workflow](/docs/develop/workflow/), [Platform shells and CLI](/docs/guides/platform-shells-cli-and-testing/), [Terminal user interfaces](/docs/guides/terminal-user-interfaces/), and [Static sites](/docs/guides/static-sites/).
+4. **Test and debug** with [Testing lifecycle](/docs/test-and-debug/overview/) and [Testing and diagnostics](/docs/guides/testing-and-diagnostics/).
+5. **Build and package** with [Packaging overview](/docs/build-and-package/overview/) and the platform-specific readiness checks.
+6. **Release and distribute** with [Release overview](/docs/release-and-distribute/overview/) and [Post-build lifecycle RFC](/docs/release-and-distribute/post-build-lifecycle/).
+7. **Look up exact contracts** in the [Reference](/reference/overview/overview/) when you know what subsystem you need.
 
-## Recommended reading path
+## How the docs are grouped
 
-If you want the smoothest introduction, read the docs in this order.
+| Section | What it answers |
+| --- | --- |
+| Start | How do I create or open a Fission project and understand its shape? |
+| Learn Fission | How do state, reducers, widgets, layout, environment, resources, and rendering fit together? |
+| Develop | How do I run the app, add targets, work with shells, and use the CLI every day? |
+| Test and debug | How do I prove behavior, inspect output, capture screenshots, and validate target-specific behavior? |
+| Build and package | How do I create installable or uploadable artifacts with readiness checks? |
+| Release and distribute | How do I ship artifacts, release content, testers, tracks, rollouts, and receipts? |
+| Reference | What are the exact API contracts, fields, widgets, chart variants, and CLI commands? |
 
-1. Start with [Learn overview](/docs/learn/overview), because it gives you the big picture of a Fission app before the details start to pile up.
-2. Move to [Quickstart](/docs/learn/quickstart), because running an example or scaffolding a small app early makes the architecture feel real instead of theoretical.
-3. Read [Runtime model](/docs/learn/runtime-model) next, because it explains what your app owns, what the runtime owns, and why Fission keeps cross-frame behavior out of your product state.
-4. Then open [Rendering pipeline](/docs/learn/rendering-pipeline), because it shows how widgets become layout, accessibility information, and painted output, which is the key to understanding debugging and performance.
-5. Continue to [Examples and targets](/docs/learn/examples-and-targets), because it connects the ideas to the repository's real desktop, web, Android, and iOS paths.
-6. When you are ready to organize your own app, read [App structure](/docs/guides/app-structure), because it turns the mental model into a project shape you can maintain.
-7. After that, pick the guide that matches your next question: [Resources and async](/docs/guides/resources-and-async) explains outside work such as background jobs, timers, and host integrations; [Platform shells and command-line interface](/docs/guides/platform-shells-cli-and-testing) explains how the shared app reaches each platform through the command-line interface and shell wrappers; and [Testing and diagnostics](/docs/guides/testing-and-diagnostics) shows how Fission turns predictable behavior into practical tests.
-8. Use [Build a counter](/docs/cookbook/build-a-counter) when you want a worked example you can follow end to end, and use [Reference overview](/reference/overview/overview) when you need exact types, fields, and function names after the bigger ideas are already familiar.
+## What to remember
 
-## How to use the rest of the docs
-
-The docs are organized by job, not only by difficulty. The Learn pages teach the model. The Guides explain real subsystems you will use while building an app. The Cookbook gives you practical recipes when you want a known-good pattern. The Reference is there for precise details when you already know what concept you are looking for.
-
-If you ever feel lost, come back to the core flow: state holds the data, actions describe intent, reducers change state, widgets render from state, and shells run the same app on each platform. That flow is the reason the rest of Fission stays understandable.
+The same app model sits underneath the lifecycle. State holds product truth. Actions describe intent. Reducers update state. Widgets render from state. Resources, commands, jobs, services, and capabilities describe outside work explicitly. Shells host that app model on desktop, web, mobile, terminal, and static site targets. The CLI then carries the project through development, packaging, release, and distribution.

documentation/content/docs/release-and-distribute/overview.mdx

@@ -0,0 +1,37 @@
+---
+title: Release and distribute
+description: Publish Fission artifacts to app stores, static hosts, object stores, GitHub Releases, testers, tracks, rollouts, and release receipts.
+---
+
+# Release and distribute
+
+Release is where package artifacts, store metadata, screenshots, credentials, tracks, testers, and provider-specific workflows meet. Fission makes that a project workflow instead of leaving every app to invent its own release scripts.
+
+## Provider families
+
+| Provider family | What Fission manages |
+| --- | --- |
+| App stores | Google Play APK/AAB upload, App Store Connect IPA upload, Microsoft Store MSI/EXE API path, Microsoft Store MSIX/MSIXUPLOAD Partner Center path through `msstore`. |
+| Static hosting | GitHub Pages, Cloudflare Pages, Netlify, custom domain readiness, and generated static site assets. |
+| Artifact distribution | GitHub Releases, S3-compatible object stores, Google Drive, OneDrive, Dropbox, and direct artifact upload receipts. |
+| Release content | Screenshots, preview videos, feature graphics, logos, trailers, notes, privacy metadata, review attachments, and provider-specific validation. |
+| Release management | Testers, beta groups, tracks, package flights, staged rollout, status queries, receipts, and CI JSON output. |
+
+## Typical release flow
+
+```bash
+fission readiness release --project-dir . --target windows --format msix --provider microsoft-store
+fission package --project-dir . --target windows --format msix --release
+fission release-content validate --project-dir . --provider microsoft-store
+fission distribute --project-dir . --provider microsoft-store --artifact target/fission/release/windows/msix/artifact-manifest.json --track public --yes
+```
+
+The exact commands vary by provider, but the shape stays consistent: check readiness, build the artifact, validate release content, publish, then keep the receipt.
+
+## Credentials
+
+Provider credentials should not be committed to the repository. Fission supports environment variables, CI secrets, authenticated provider tools, and its encrypted release credential vault. The project manifest stores references and provider metadata, while secrets stay outside plain-text project config.
+
+## Where to go next
+
+Read [Production lifecycle](/product/production-lifecycle/) for the high-level model, [Build and package](/docs/build-and-package/overview/) for artifacts, and [Post-build lifecycle](/docs/release-and-distribute/post-build-lifecycle/) for the RFC-level detail.