Product website and learning documentation — presentation, guides, support, and store readiness

[Flow-Fly]

Parent initiative: #72
Related observability capability: #401
Related onboarding capability: #402
Related mobile/store capability: #382

Outcome

Give visitors a clear public explanation of Pixel Forge and give users a durable, searchable learning surface for the editor, while also preparing the public support and privacy pages required by future Play Store and App Store distribution.

This is a capability-level roadmap issue, not one delivery slice. It must be split after the information architecture, hosting path, product positioning, and initial content are approved.

Product roles

The public surface has two related jobs:

Product presentation

Explain quickly:

• what Pixel Forge is;
• who it is for;
• that it is local-first and works offline;
• which drawing, animation, palette, Guided Drawing, import, and export capabilities exist;
• why someone should try it;
• what optional cloud sync will add later.

Learning documentation

Help users complete concrete tasks:

• create and manage projects;
• understand tools and tool options;
• draw and edit pixel art;
• work with palettes;
• create an animation with frames, timing, onion skinning, and playback;
• use Guided Drawing;
• import and export supported formats;
• install and use the PWA offline;
• recover, back up, and move local projects;
• use keyboard shortcuts;
• understand local versus future cloud storage.

The in-app guide in #402 teaches interactively. These pages remain the durable reference and should link directly to relevant tutorial entry points where practical.

Initial information architecture

Candidate first release:

1. Landing/product page
2. Features
3. Create your first pixel art
4. Create your first animation
5. Guided Drawing
6. Tools reference
7. Animation and timeline reference
8. Palettes and color
9. Import, export, and file formats
10. Keyboard shortcuts
11. Install and offline use
12. Local storage, backup, and recovery
13. Cloud sync preview / future plans
14. FAQ
15. Privacy
16. Support / contact
17. Terms when accounts or paid services require them

Keep the first release intentionally small. A concise, accurate page is better than a generated documentation inventory that users cannot navigate.

Product media

Use real Pixel Forge output and interface captures:

• short, compressed demonstrations rather than decorative stock imagery;
• a small animation created by the First-run onboarding — welcome flow, interface presentation, and first animation #402 tutorial;
• Guided Drawing before/during/result examples;
• desktop and later mobile/store screenshots;
• meaningful alt text and reduced-motion alternatives.

Avoid publishing private user artwork without explicit permission.

Technical direction

Prefer a lightweight static site or static documentation build with minimal JavaScript. Do not introduce a CMS initially.

Decide whether it should be:

• a separate static entry/deployment in this repository;
• a dedicated documentation application in the same repository;
• or a separate repository only if independent ownership/deployment genuinely warrants it.

Do not move the existing editor URL or break installed-PWA behavior merely to add a marketing landing page. URL structure, canonical links, redirects, CSP, deployment, and offline caching need an explicit plan.

Reuse product wording and tutorial content between the public site and #402 without coupling the editor runtime to a documentation framework.

Store-readiness relationship

#382 already owns mobile packaging and store delivery. This capability supplies or prepares the public web surfaces it will need:

• stable support URL;
• privacy policy URL;
• account/data deletion explanation once auth exists;
• screenshots and product descriptions grounded in the real mobile experience;
• release notes/help entry points;
• links that work outside the installed application.

Store-specific declarations and submission remain in #382, not here.

Observability and privacy

• Use Product observability — activation funnel, client errors, and backend telemetry boundaries #401 for aggregate traffic, page performance, documentation searches or approved meaningful navigation events.
• Do not embed invasive session replay or advertising trackers.
• Explain clearly what stays local, what future sync uploads, and what observability collects.
• Update privacy/account documentation alongside auth, sync, mobile, and billing changes.

Delivery outline

1. Approve positioning, audience, voice, and URL architecture.
2. Inventory the current editor behavior and identify documentation owners.
3. Build the minimal static shell, navigation, metadata, accessibility, and deployment path.
4. Publish the product page plus first-animation and storage/recovery guides.
5. Add the core reference pages.
6. Add privacy and support pages suitable for the current web product.
7. Extend with mobile/store material only after physical mobile behavior exists.
8. Add a documentation accuracy check to relevant feature delivery.

Capability acceptance

• A new visitor can understand the product and reach the editor quickly.
• A user can find and complete the first-animation workflow without guessing.
• Documentation describes the current product rather than planned behavior as if it exists.
• Local storage, backup, privacy, and future cloud behavior are clearly distinguished.
• Navigation, headings, focus, contrast, media alternatives, and common viewport sizes pass accessibility/responsive review.
• Pages have appropriate titles, descriptions, social metadata, canonical URLs, sitemap, and robots behavior.
• Static pages remain fast and useful with minimal client JavaScript.
• The support and privacy URLs needed by Mobile apps — adaptive touch editor and cross-device projects #382 are stable.
• Content has an explicit maintenance owner or update contract.
• The work is split into bounded delivery slices before implementation.

Decisions required before slicing

• Primary audience and product positioning.
• Existing domain versus subdomain/path structure.
• Same repository/deployment versus a dedicated documentation project.
• Initial visual direction and approved product media.
• Contact/support channel.
• Privacy/terms review process.
• Which languages are supported initially.
• Which pages must exist before the first Play Store test release.

Non-goals

• No CMS or editorial workflow platform for the first release.
• No community forum or marketplace.
• No promise that planned cloud/mobile functionality is already available.
• No disruption of the installed PWA/editor URL without a migration plan.
• No copying internal engineering documentation directly into user-facing pages.