Error-Zhang · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,51 @@
+# Contributing to VelarScript
+
+VelarScript is still a pre-1.0 language and Web framework. Changes should make
+the language clearer or the Web development loop more complete; compatibility
+with an accidental earlier implementation is not a goal by itself.
+
+## Ownership boundaries
+
+- `packages/compiler` owns Core syntax, types, analysis, JavaScript emission,
+  semantic metadata, and extension/framework-host protocols.
+- `packages/web` owns JSX, components, reactivity, lifecycle, browser types,
+  Web runtime behavior, and deployment projection.
+- `packages/cli` composes installed extensions and owns generic project,
+  package, build, test, preview, and LSP processes. It must not become a second
+  Web framework.
+- `packages/create` owns transactional project templates.
+- The independent Workbench repository is a generic editor host. Language
+  intelligence must arrive from the project-local Velar LSP.
+
+## Language and API changes
+
+A user-visible language change should update the language charter, diagnostics,
+compiler/runtime behavior, semantic tooling, and focused tests together. If a
+real application exposes an awkward rule, fix the language or framework seam
+instead of adding an application-only workaround.
+
+Keep the type layer small and operational. Do not introduce TypeScript-style
+type-level programming, hidden JavaScript coercion, ambient browser globals, or
+a second runtime model. JavaScript interop must cross an explicit checked
+boundary.
+
+## Local validation
+
+VelarScript requires Node.js 24 or later and npm.
+
+```sh
+npm ci
+npm run check
+npm test
+npm run test:packages
+npm run test:browser
+```
+
+The browser gate installs and exercises Chromium, Firefox, and WebKit. A change
+that touches packaging or delivery should also run the non-publishing release
+rehearsal documented in `docs/release-process.md`. Editor-facing changes must
+be checked through a packed toolchain in the independent Workbench gate; do not
+link compiler source into the editor.
+
+Do not publish npm packages, create a stable tag, deploy a preview, or weaken a
+release blocker as part of an ordinary contribution.
diff --git a/README.md b/README.md
@@ -1,10 +1,32 @@
 # VelarScript
 
+[![Velar CI](https://github.com/VelarOS-AI/VelarScript/actions/workflows/ci.yml/badge.svg)](https://github.com/VelarOS-AI/VelarScript/actions/workflows/ci.yml)
+
 VelarScript is a clean, Web-first language compiled by the Velar Compiler to
 modern JavaScript, CSS, and Web assets. It keeps the JavaScript runtime and
 replaces the source surface with a smaller Python/JavaScript blend designed for
 Web applications.
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the compiler/framework boundary and
+validation workflow. Security-sensitive reports belong in GitHub's private
+security-advisory flow described in [SECURITY.md](SECURITY.md), not a public
+issue.
+
+```sh
+npm create velar@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Use `-- --template docs` for a routed documentation site,
+`-- --template library` for a Core `.vel` source package, or
+`-- --template component` for a reusable Web component package. The same
+templates are available through `velar create` once the CLI is installed.
+Velar keeps npm as the registry and lockfile authority; after bootstrap,
+`velar install`, `velar add`, `velar remove`, and `velar update` provide the
+project-aware dependency surface.
+
 This repository was rebuilt from zero. It does not retain source code, Git
 history, architecture, or language semantics from the former VelarScript
 project.
@@ -13,7 +35,11 @@ project.
 
 Velar 0.9AB has completed the internal application-scale language-and-Web
 sequence, and the requirement-by-requirement 1.0 internal engineering audit is
-complete. Publication and external deployment are deliberately deferred. Its first pass
+complete. The audited development source is published through
+[draft PR #1](https://github.com/VelarOS-AI/VelarScript/pull/1), and the
+[official Website source](https://github.com/VelarOS-AI/VelarScript-Website)
+is a separate Apache-2.0 project that dogfoods the packed toolchain. npm
+publication and hosted deployment remain deliberately deferred. The audit's first pass
 closes the ordinary new-project workflow: generated applications now contain a
 separate app module, a real Core test, a browser test, project-wide format
 scripts, and an installed-package acceptance that uses only those generated
@@ -50,7 +76,8 @@ complete supported Web attributes/directives, and typed object literals
 complete their missing record fields. Value expressions immediately return to
 ordinary lexical completion. This is internal readiness
 evidence, not a public production claim: hosted preview observation, independent
-users, a stable version/tag, a matching remote, and publish authority remain
+users, review and merge of the development source, a stable version/tag, and
+publish authority remain
 external.
 
 Failure containment is now a retained gate rather than an assumption. Compile,
@@ -362,7 +389,7 @@ configuration, structured leveled logging, lazy root mounting, last-valid-DOM
 retention, async mounted blocks, and failure-tolerant cleanup.
 0.7C adds project-owned `.browser.test.vel` suites through
 `velar test --browser`, a generated-project test, packed-CLI browser execution,
-a root-base Netlify deployment adapter, 0.3–0.6 upgrade fixtures, and repeated
+a root-base Netlify deployment adapter, clean format-2 project contracts, and repeated
 route/cleanup production soak. 0.7D closes the production-artifact loop with strict
 `velar verify` integrity checks and `velar preview`, which refuses to serve an
 unverified or modified build. External preview and release authority remain
@@ -387,22 +414,28 @@ cross-module inherited-member analysis. 0.6B adds the independently versioned
 Core Standard API, and 0.6C establishes its initial surface. Standard API 0.4
 now contains 133 exports across collections, text, math, JSON, async, URL,
 time, secure IDs, and structured logging modules. Compiler-owned
-lightweight polymorphic inference replaces user-facing generics. The compiler
-and CLI build
-reproducible, version-locked JavaScript plus `.d.ts` tarballs with SHA-256 and
-source identity, while rehearsal and strict candidate modes remain incapable
-of silently publishing. GitHub CI covers Node 24 on Linux, macOS, and Windows
-plus development and production Web flows in three browser engines.
+lightweight polymorphic inference replaces user-facing generics. The compiler,
+official `@velarscript/web` framework, project creator, and CLI build reproducible,
+version-locked JavaScript plus `.d.ts` tarballs with SHA-256 and source
+identity, while rehearsal and strict candidate modes remain incapable of
+silently publishing. GitHub CI covers Node 24 on Linux, macOS, and Windows plus
+development and production Web flows in three browser engines.
 
 Velar source libraries use npm itself: a package publishes `.vel` source with
 `package.json` `velar.entry`, and the compiler checks and bundles that source as
-part of the application graph. Development builds provide compile/runtime
+part of the application graph. Compiler/framework packages opt into automatic
+project activation through generic `velar.extension` metadata. The CLI passes
+registry package operations to npm without a shell, leaves dependency and lock
+ownership there, and atomically changes only `velar.json` extension fields.
+Development builds provide compile/runtime
 overlays, `.vel` stack mapping, full-graph hot invalidation, and a
 machine-readable status endpoint. Production builds use isolated staging,
 emit hashed assets, strict CSP metadata, static-host fallback/header/cache
-contracts, and deterministic format-2 build identity with SHA-256 identities.
+contracts, and deterministic format-3 framework build identity with SHA-256
+identities. The manifest records the framework package, capability, target,
+host-protocol version, API version, and framework artifact kind.
 
-The stable Web API is independently versioned at 0.6. Ten explicit Web
+The stable Web API is independently versioned at 0.8. Ten explicit Web
 modules provide base-aware routing and metadata, typed HTTP, local/session/
 IndexedDB persistence, accessible forms, browser environment helpers,
 cross-browser files, WebSocket/SSE realtime connections, typed tests,
@@ -411,8 +444,8 @@ Implicit browser globals are rejected in ordinary Velar source and diagnostics
 lead to these modules or an explicit JavaScript boundary. The 15-module Release
 Studio passes Chromium, Firefox, and WebKit against both the development server
 and the CSP-enabled static production build. Packed toolchains also run through
-the real generic Workbench LSP host. The 0.6 language and API implementation is
-the foundation now being hardened toward production use in 0.7.
+the real generic Workbench LSP host. The 0.6 language baseline and Web API 0.8
+are the foundation now being hardened toward production use.
 `velar/game`, SSR/server execution, a custom package registry, and a custom
 debug protocol remain deferred.
 
@@ -457,17 +490,18 @@ node dist/core.js
 Run a Web application with live recompilation:
 
 ```sh
-npm run velar -- dev examples/todo/main.vel
+npm run velar -- dev examples/todo
 ```
 
 A normal project uses `velar.json`, so commands need no entry argument:
 
 ```json
 {
-  "formatVersion": 1,
+  "formatVersion": 2,
   "entry": "src/main.vel",
   "outDir": "dist",
   "publicDir": "public",
+  "extensions": ["@velarscript/web"],
   "web": {
     "title": "My Velar App",
     "base": "/",
@@ -491,16 +525,21 @@ npm run velar -- verify-deployment examples/production-web --url https://preview
 npm run preview:prepare
 ```
 
-Create a new project or inspect an older project before upgrading it:
+Create and validate a new project:
 
 ```sh
 npm run velar -- create my-app
 npm run velar -- format my-app --check
 npm run velar -- test my-app
-npm run velar -- upgrade my-app --check
-npm run velar -- upgrade my-app
 ```
 
+Format 2 is a clean break: Core projects declare `"extensions": []`; Web
+projects install and declare `@velarscript/web`. Legacy manifests are rejected
+instead of upgraded implicitly or through a compatibility command.
+The project loader discovers the package's independent `/compiler` and `/host`
+entries. Web owns HTML, CSP, reload, deployment projection, and browser-test
+metadata; CLI owns only generic host mechanics.
+
 Build a Web application:
 
 ```sh
@@ -543,6 +582,8 @@ A reusable Velar package publishes source through ordinary npm metadata:
 
 Applications import it normally: `import {Button} from "my-velar-library"`.
 Package-relative `.vel` imports are confined to the package root.
+Reusable Web components follow the same source-package path with an explicit
+Web peer contract; see [docs/component-packages.md](docs/component-packages.md).
 
 Start the language server used by VelarOS Workbench:
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported versions
+
+VelarScript has no stable production release yet. The current development line
+receives security fixes, but its internal 1.0 acceptance is not a production
+support claim.
+
+## Reporting a vulnerability
+
+Use the repository's **Security → Report a vulnerability** flow to open a
+private GitHub security advisory. Do not disclose an exploitable compiler,
+development-server, package-boundary, generated-output, browser-runtime, or
+deployment-verification issue in a public issue before it is contained.
+
+Include the affected commit or package version, operating system and Node.js
+version, the smallest reproduction available, expected and observed behavior,
+and the security impact. Avoid placing real credentials, private source, or
+personal data in the report.
+
+After confirmation, the fix should add a focused regression test at the owning
+boundary. Publication timing and disclosure are coordinated through the
+private advisory rather than inferred from ordinary release automation.
diff --git a/docs/0.3-acceptance.md b/docs/0.3-acceptance.md
@@ -43,7 +43,7 @@ Packaging:   bun run package:app:dir && bun run verify:app:dir
 ## Next big stage
 
 Velar 0.4 is the distribution and broader Web-application stage: publishable
-compiler/CLI packages, project creation and upgrade policy, a deliberately
+toolchain packages, project creation and version policy, a deliberately
 limited TypeScript declaration bridge for real npm libraries, broader browser
 coverage, and deeper routing/forms/head/accessibility APIs. SSR/server,
 `velar/game`, a custom package registry, a custom debug protocol, and complex

diff --git a/docs/0.4-acceptance.md b/docs/0.4-acceptance.md
@@ -1,16 +1,17 @@
 # VelarScript 0.4 Acceptance Matrix
 
-Status: distribution and broader Web-application milestone complete
+Status: historical milestone; its project-lifecycle contract is superseded by
+the format-v2 explicit-extension clean break
 
 ## Distribution and projects
 
 | Contract | Evidence |
 | --- | --- |
-| Compiler and CLI publish JavaScript plus `.d.ts`, require Node 24, and remain independent from Workbench | Package manifests and build tsconfigs |
-| Packed tarballs install and run in a clean consumer | `npm run test:packages`: installed CLI version/build and compiler API probe |
-| CLI/compiler versions are exact and package contents exclude repository tests | Tarball contract assertions |
-| `velar create` refuses non-empty targets and creates a usable versioned project | Project lifecycle integration test |
-| Legacy manifests upgrade explicitly; future versions fail closed | `velar upgrade --check`, write upgrade, and formatVersion 99 rejection |
+| Compiler, Web, creator, and CLI publish JavaScript plus `.d.ts`, require Node 24, and remain independent from Workbench | Package manifests and build tsconfigs |
+| Packed tarballs install and run in a clean consumer | `npm run test:packages`: installed CLI version/build, Web extension, creator, and compiler API probes |
+| Release-set versions are exact and package contents exclude repository tests | Tarball contract assertions |
+| `velar create` refuses non-empty targets and creates a usable format-v2 project | Project lifecycle integration test |
+| Legacy manifests and unknown future versions fail closed | Format-v1 and formatVersion 99 rejection; there is no compatibility loader or upgrade command |
 
 ## JavaScript ecosystem boundary
 
@@ -37,7 +38,7 @@ Status: distribution and broader Web-application milestone complete
 | Contract | Evidence |
 | --- | --- |
 | Workbench remains generic and consumes LSP protocol v1 | Product-boundary and language-support tests |
-| Versioned project upgrade check is injected as generic command metadata | Workbench Velar contribution test |
+| Project checking is injected as generic command metadata | Workbench Velar contribution test |
 | Installed toolchain is resolved project-locally | Workbench language-service descriptor and package-consumer gate |
 
 ## Acceptance commands

diff --git a/docs/0.5-acceptance.md b/docs/0.5-acceptance.md
@@ -6,7 +6,7 @@ Status: pre-release productization milestone complete
 
 | Contract | Evidence |
 | --- | --- |
-| Compiler and CLI tarballs have one exact version and dependency identity | Release rehearsal manifest and package consumer test |
+| Compiler, Web, creator, and CLI tarballs have one exact version and dependency identity | Release rehearsal manifest and package consumer test |
 | Unchanged sources create identical package SHA-256 identities | Repeated rehearsal assertion |
 | Rehearsal records source/tree/package identity and never publishes | `velar-toolchain-release.json`, workflow/source assertions |
 | Strict candidates require stable version, clean tagged commit, matching remote, and license | Candidate refusal test |
@@ -36,7 +36,7 @@ Status: pre-release productization milestone complete
 
 | Contract | Evidence |
 | --- | --- |
-| Workbench installs packed compiler/CLI tarballs into a temporary project | `test:velar:installed` |
+| Workbench installs the packed compiler/Web/creator/CLI release set into a temporary project | `test:velar:installed` |
 | Generic Workbench resolves project-local `node_modules/.bin/velar` | Installed-toolchain LSP acceptance |
 | Diagnostics and completion come from the installed LSP with protocol v1 | Cross-repository acceptance result |
 | Workbench contains no compiler dependency or duplicated Velar semantics | Existing product-boundary tests |

diff --git a/docs/0.7-acceptance.md b/docs/0.7-acceptance.md
@@ -31,18 +31,18 @@ Status: internal 0.7A–0.7G engineering gate complete; external preview remains
 | Real Web behavior is cross-browser | Release Studio exercises config, logs, async event failure, failed render retention, mounted work, and cleanup continuation in Chromium, Firefox, and WebKit for development and CSP production |
 | Editor behavior stays injected | The installed-toolchain Workbench gate requests `velar/app`, `velar/config`, and `velar/log` completion through the generic project-local LSP host |
 
-## 0.7C project testing, deployment, upgrade, and soak
+## 0.7C project testing, deployment, extension boundary, and soak
 
 | Contract | Evidence |
 | --- | --- |
 | Browser tests belong to projects | `.browser.test.vel` and `velar test --browser` are product contracts; Core discovery excludes browser files and generated projects include a passing browser test/script |
-| Automation stays small and typed | `velar/test.browser` exposes only navigation, interaction, observation, waiting, path, and viewport methods; raw DOM/Playwright evaluation is not exposed |
+| Automation stays small and typed | `velar/web-test.browser` exposes only navigation, interaction, observation, waiting, path, and viewport methods; raw DOM/Playwright evaluation is not exposed |
 | Tests exercise production reality | The CLI builds an isolated CSP production site, serves the deployment contract, creates a fresh context per test, and fails page/console runtime errors automatically |
 | The browser matrix is selectable | Chromium is the local default and explicit Chromium, Firefox, WebKit, and `all` modes pass Release Studio recovery and eight-cycle route/cleanup soak scenarios (6/6 project flows) |
-| Packed CLI carries the feature | A clean consumer installs packed compiler/CLI tarballs, creates a project, and passes its generated browser test in real Chromium |
+| Packed CLI carries the feature | A clean consumer installs packed compiler/Web/creator/CLI tarballs, creates a project, and passes its generated browser test in real Chromium |
 | One real host adapter exists | Root-base `adapter: "netlify"` translates manifest headers and SPA fallback to official `_headers` and `_redirects`; non-root base fails closed |
 | Adapter output is release identity | Provider files are compiler-reserved, receive `adapter` asset roles, sizes and SHA-256 values, and participate in `buildId` |
-| Previous projects remain usable | Fixed 0.3, 0.4, 0.5, and 0.6 fixtures all pass read-only upgrade inspection, explicit upgrade, current semantic check, and production build |
+| The clean break is explicit | Generated projects use format 2 and declare `@velarscript/web`; missing, format-1, and unknown future manifests fail closed without a compatibility loader or rewrite command |
 | Workbench remains a generic host | Only the injected Velar contribution adds Browser Test command metadata; the shared editor/project-command host remains free of Velar branches |
 
 ## 0.7D verified production artifacts
@@ -98,10 +98,10 @@ Status: internal 0.7A–0.7G engineering gate complete; external preview remains
 
 ## API and format versions
 
-Velar language/toolchain version `0.7.0-dev` uses Standard API `0.3`, Web API
-`0.6`, project format `1`, build manifest format `2`, and LSP protocol `1`.
-The additive manifest/API work requires neither a project migration nor a
-Workbench host protocol branch.
+The current `0.9.0-dev` toolchain retains Standard API `0.4`, Web API `0.7`,
+build manifest format `2`, and LSP protocol `1`. Project format `2` is a clean
+break with explicit extensions; no legacy loader or migration command remains,
+and the generic Workbench host protocol is unchanged.
 
 ## Remaining production gate