feat: Review & improve documentation before release

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -48,4 +48,4 @@ body:
     id: context
     attributes:
       label: Additional Context
-      description: Add any other context, screenshots, or .sw.json / .sw.yaml snippets here.
+      description: Add any other context, screenshots, or .json / .yaml snippets here.

CONTRIBUTING.md

@@ -50,10 +50,16 @@ pnpm run build:prod
 
 ## Development Environment
 
-This project uses the following core technology stack:
+This project uses the following technology stack:
 
-- **Language**: [TypeScript](https://www.typescriptlang.org/) (for type safety and maintainability)
-- **Library**: [React](https://react.dev/) (for building the user interface)
+- **Language**: [TypeScript](https://www.typescriptlang.org/) with strict mode enabled
+- **UI Library**: [React](https://react.dev/)
+- **Diagram Rendering**: [@xyflow/react](https://reactflow.dev/) (isolated in `src/react-flow/`)
+- **Workflow SDK**: [@serverlessworkflow/sdk](https://github.com/serverlessworkflow/sdk-typescript) (isolated in `src/core/`)
+- **Testing**: [Vitest](https://vitest.dev/) for unit tests, [Playwright](https://playwright.dev/) for E2E
+- **Linting**: [oxlint](https://oxc.rs/) with TypeScript, React, import, and jsx-a11y plugins
+- **Formatting**: [oxfmt](https://oxc.rs/)
+- **Component Development**: [Storybook](https://storybook.js.org/)
 
 The project aims for the editor to be **embeddable**, with the core logic decoupled from specific platform APIs (like VS Code or Chrome APIs) through an abstraction layer.
 
@@ -63,7 +69,7 @@ If you find a bug or have a question, please check the [existing issues](https:/
 
 1. Open a new issue using the appropriate template.
 2. Provide a clear description of the problem.
-3. Include steps to reproduce the bug and provide a sample workflow file (`.sw.json` or `.sw.yaml`) if applicable.
+3. Include steps to reproduce the bug and provide a sample workflow file (`.json` or `.yaml`) if applicable.
 
 ## Suggesting a Change
 
@@ -110,12 +116,68 @@ If you're unsure whether your use of agents/LLMs is acceptable — ask! We're ha
 
 > This isn't about banning AI — it's about keeping this project collaborative, human-driven, and focused on quality.
 
+## Git Hooks
+
+The project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks automatically after `pnpm install`:
+
+- **`pre-commit`**: Runs `lint-staged` to automatically format staged files matching `*.{ts,tsx,js,jsx,json,md,yml,yaml}` using oxfmt.
+- **`commit-msg`**: Validates that commits include a DCO `Signed-off-by` line. Commits without sign-off will be rejected.
+
+These hooks help maintain code quality and ensure compliance with project requirements.
+
+## Testing
+
+The project uses multiple testing strategies:
+
+### Unit Tests
+
+Unit tests are written using [Vitest](https://vitest.dev/) with React Testing Library. Tests mirror the source structure in `tests/`:
+
+```bash
+cd packages/serverless-workflow-diagram-editor
+pnpm test
+```
+
+### End-to-End Tests
+
+E2E tests use [Playwright](https://playwright.dev/) and are located in `tests-e2e/`:
+
+```bash
+cd packages/serverless-workflow-diagram-editor
+pnpm test-e2e          # Run tests headless
+pnpm test-e2e:ui       # Run with Playwright UI
+```
+
+Before running E2E tests for the first time, install Playwright browsers:
+
+```bash
+# From root directory
+pnpm playwright:install:ci
+```
+
+### Type Checking
+
+Run TypeScript type checking:
+
+```bash
+cd packages/serverless-workflow-diagram-editor
+pnpm typecheck
+```
+
+## Continuous Integration
+
+Pull requests automatically trigger:
+
+- **Netlify Deploy Previews**: Storybook is automatically built and deployed for PRs that modify the `@serverlessworkflow/diagram-editor` package, allowing reviewers to preview changes interactively.
+- **Automated Checks**: Linting, type checking, tests, and builds must pass before merging.
+
 ## Pull Request Process
 
 1. **Fork** the repository and create your branch from `main`.
 2. **Commit** your changes with clear, descriptive messages.
-3. **Verify** your changes by running the appropriate build and/or test commands for the packages you modified.
-4. If your PR changes a package, run `pnpm changeset` and commit the generated `.changeset/*.md` file.  
+3. **DCO Sign-off**: As a CNCF project, all commits must be signed off (`git commit -s`) to certify the Developer Certificate of Origin. The `commit-msg` hook will automatically verify sign-off is present.
+4. **Verify** your changes by running the appropriate build and/or test commands for the packages you modified.
+5. If your PR changes a package, run `pnpm changeset` and commit the generated `.changeset/*.md` file.  
    As an alternative you may prefer to compare against upstream explicitly:
 
    ```bash
@@ -128,8 +190,7 @@ If you're unsure whether your use of agents/LLMs is acceptable — ask! We're ha
    git remote add upstream https://github.com/serverlessworkflow/editor.git
    ```
 
-5. **Submit** a Pull Request (PR).
-6. **DCO Sign-off**: As a CNCF project, all commits must be signed off (`git commit -s`) to certify the Developer Certificate of Origin.
+6. **Submit** a Pull Request (PR).
 7. **Review**: At least one maintainer must review and approve your PR before it is merged.
 
 ---

README.md

@@ -16,18 +16,27 @@
 
 # editor
 
-CNCF Serverless Workflow Specification Visual Editor
+The official **vendor-neutral visual editor** for the [Open Workflow Specification](https://github.com/serverlessworkflow/specification).
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![CNCF Sandbox](https://img.shields.io/badge/CNCF-Sandbox-informational)](https://www.cncf.io/projects/serverless-workflow/)
+
+## Overview
+
+This project provides an interactive, visual diagram editor designed to be:
+
+- **Vendor-neutral**: No platform-specific dependencies
+- **Embeddable**: Core logic decoupled from platform APIs (VS Code, browser extensions, etc.)
+- **Specification-first**: Built around the official Open Workflow Specification
 
 ## Prerequisites
 
 To build and run the editor locally, you will need:
 
-- **Node.js 22** (current LTS version; see https://nodejs.org/)
-- **pnpm 10.31.0**
+- **Node.js**: `^22.13.0 || >=24.0.0` (see [nodejs.org](https://nodejs.org/))
+- **pnpm**: `10.31.0` (exact version, enforced by `packageManager` field)
 
-## Building the Project
-
-The project is structured as a monorepo to support multiple distribution targets (Web, VS Code, etc.) as defined in our architectural decisions.
+## Quick Start
 
 ```bash
 # Clone the repository
@@ -37,30 +46,183 @@ cd editor
 # Install dependencies
 pnpm install
 
-# Build all packages in the monorepo (development)
+# Build all packages (development)
 pnpm run build:dev
 
-# Or build all packages in the monorepo (production)
+# Or build all packages (production - includes linting and tests)
 pnpm run build:prod
 ```
 
+## Development
+
+### Running Storybook
+
+Storybook provides an interactive development environment for the diagram editor:
+
+```bash
+cd packages/serverless-workflow-diagram-editor
+pnpm start  # Starts Storybook on http://localhost:6006
+```
+
+### Running Tests
+
+```bash
+cd packages/serverless-workflow-diagram-editor
+
+# Unit tests (Vitest)
+pnpm test
+
+# E2E tests (Playwright)
+pnpm test-e2e          # Headless
+pnpm test-e2e:ui       # With Playwright UI
+
+# Type checking
+pnpm typecheck
+
+# Linting
+pnpm lint
+```
+
+Before running E2E tests for the first time:
+
+```bash
+# From root directory
+pnpm playwright:install:ci
+```
+
+### Code Quality
+
+```bash
+# Format all files
+pnpm format
+
+# Check formatting without modifying
+pnpm format:check
+
+# Check dependency versions across packages
+pnpm dependencies:check
+
+# Fix dependency version mismatches
+pnpm dependencies:fix
+```
+
 ## Repository Structure
 
 ```
 editor/
-├── .github/                    # CI workflows, issue templates, Dependabot
-├── .husky/                     # Git hooks (commit-msg, pre-commit)
+├── .github/                    # CI workflows, issue templates, Dependabot config
+├── .husky/                     # Git hooks (commit-msg for DCO, pre-commit for linting)
+├── adr/                        # Architecture Decision Records
 ├── packages/                   # Monorepo workspace packages
+│   ├── serverless-workflow-diagram-editor/  # Main diagram editor component
+│   └── i18n/                   # Internationalization utilities
+├── .changeset/                 # Changesets for version management
 ├── .oxfmtrc.json               # Formatter config (oxfmt)
 ├── .oxlintrc.json              # Linter config (oxlint)
 ├── .syncpackrc.json            # Monorepo package version consistency
-├── netlify.toml                # Netlify configuration for Storybook preview deployment
-├── pnpm-workspace.yaml         # pnpm workspace definition
-└── tsconfig.base.json          # Shared TypeScript config
+├── netlify.toml                # Netlify configuration for Storybook previews
+├── pnpm-workspace.yaml         # pnpm workspace definition with catalog dependencies
+├── tsconfig.base.json          # Shared TypeScript config (strict mode enabled)
+└── CONTRIBUTING.md             # Contribution guidelines
 ```
 
-### Key Packages
+## Packages
+
+### [@serverlessworkflow/diagram-editor](./packages/serverless-workflow-diagram-editor)
+
+The main visual diagram editor component built with:
+
+- **TypeScript** (strict mode)
+- **React**
+- **[@xyflow/react](https://reactflow.dev/)** for diagram rendering (isolated in `src/react-flow/`)
+- **[@serverlessworkflow/sdk](https://github.com/serverlessworkflow/sdk-typescript)** (isolated in `src/core/`)
+- **[shadcn/ui](https://ui.shadcn.com/)** for UI primitives (with `dec:` Tailwind prefix)
+- **[Storybook](https://storybook.js.org/)** for component development
+- **[Vitest](https://vitest.dev/)** and **[Playwright](https://playwright.dev/)** for testing
+
+### [@serverlessworkflow/i18n](./packages/i18n)
+
+Internationalization utilities used by the diagram editor.
+
+## Technology Stack
+
+- **Language**: [TypeScript](https://www.typescriptlang.org/) with strict mode
+- **UI Framework**: [React](https://react.dev/)
+- **Diagram Library**: [@xyflow/react](https://reactflow.dev/) (React Flow)
+- **Auto Layout**: [ELK.js](https://eclipse.dev/elk/)
+- **Workflow SDK**: [@serverlessworkflow/sdk](https://github.com/serverlessworkflow/sdk-typescript)
+- **UI Components**: [shadcn/ui](https://ui.shadcn.com/) + [Radix UI](https://www.radix-ui.com/)
+- **Styling**: [Tailwind CSS](https://tailwindcss.com/)
+- **Testing**: [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/)
+- **Linting**: [oxlint](https://oxc.rs/)
+- **Formatting**: [oxfmt](https://oxc.rs/)
+- **Component Development**: [Storybook](https://storybook.js.org/)
+- **Build Tool**: [Vite](https://vite.dev/)
+- **Package Manager**: [pnpm](https://pnpm.io/)
+
+## Architecture
+
+The diagram editor maintains strict separation of concerns:
+
+- **SDK Isolation**: SDK integration helpers live under `src/core/` (e.g., `workflowSdk.ts`, `graph.ts`, `taskSubType.ts`, `taskDetails.ts`, `mermaidExport.ts`); other layers may also import SDK types/enums (e.g., `Specification`, `GraphNodeType`) when needed.
+- **React Flow Isolation**: React Flow rendering components live in `src/react-flow/` (nodes/edges/diagram); other layers may import `@xyflow/react` types and/or `ReactFlowProvider`.
+- **Platform Agnostic**: Core logic decoupled from platform-specific APIs
+- **Embeddable**: Designed for integration into VS Code, web apps, and browser extensions
+
+See [adr/](./adr/) for Architecture Decision Records.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details on:
+
+- Setting up your development environment
+- Coding standards and best practices
+- Testing requirements
+- Pull request process
+- DCO sign-off requirements (required for all commits)
+
+### DCO Sign-off
+
+As a CNCF project, all commits must include a `Signed-off-by` line:
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+The `commit-msg` hook will automatically verify DCO compliance.
+
+## Continuous Integration
+
+- **Automated Testing**: All PRs run linting, type checking, unit tests, and E2E tests
+- **Netlify Previews**: Storybook is automatically deployed for PRs modifying the diagram editor package
+- **Dependency Updates**: Automated via Dependabot
+- **License Header Checks**: Apache 2.0 headers verified on all source files
+
+## Release Process
+
+This project uses [Changesets](https://github.com/changesets/changesets) for version management:
+
+```bash
+# Create a changeset when making package changes
+pnpm changeset
+
+# Or compare against upstream explicitly
+pnpm changeset --since upstream/main
+```
+
+See [RELEASE_PROCESS.md](./RELEASE_PROCESS.md) for details.
+
+## Community
+
+- **Slack**: Join [#serverless-workflow](https://cloud-native.slack.com/archives/C06PYFT9HTZ) on [CNCF Slack](https://slack.cncf.io/)
+- **Issues**: [GitHub Issues](https://github.com/serverlessworkflow/editor/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/serverlessworkflow/editor/discussions)
+
+## License
+
+This project is licensed under the [Apache License 2.0](LICENSE).
 
-#### packages/serverless-workflow-diagram-editor/
+## Related Projects
 
-The visual diagram editor for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification/). Built with React Flow for interactive diagram rendering and includes Storybook for component development.
+- [Open Workflow Specification](https://github.com/serverlessworkflow/specification)
+- [Serverless Workflow SDK (TypeScript)](https://github.com/serverlessworkflow/sdk-typescript)