strengthen open source project foundations

Repair and validate documentation links, add a current bilingual project story and roadmap, define governance and community standards, publish an unreleased changelog, and automate ownership, dependency updates, and Gallery submissions.

Author: everettjf

.github/CODEOWNERS

@@ -0,0 +1,6 @@
+* @everettjf
+
+/Shared/ScriptWidgetRuntime/ @everettjf
+/Gallery/ @everettjf
+/.github/ @everettjf
+/SECURITY.md @everettjf

.github/ISSUE_TEMPLATE/gallery_submission.yml

@@ -0,0 +1,53 @@
+name: Gallery submission
+description: Propose a reviewed Widget or AI Skill for the curated Gallery.
+title: "[Gallery]: "
+labels: [gallery]
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Package kind
+      options: [Widget, Skill]
+    validations:
+      required: true
+  - type: input
+    id: identifier
+    attributes:
+      label: Stable package identifier and version
+      placeholder: app.example.widget · 1.0.0
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: User outcome
+      description: Explain who this helps, what it does, and why it belongs in the curated Gallery.
+    validations:
+      required: true
+  - type: textarea
+    id: trust
+    attributes:
+      label: Data, network, permissions, AI, and privacy
+      description: List every network domain and permission, stored data, sensitive input, AI behavior, and fallback. Write “none” where applicable.
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification evidence
+      description: Include platforms/families tested, screenshots for Widgets, Prompt examples for Skills, and the release-readiness result.
+    validations:
+      required: true
+  - type: checkboxes
+    id: confirmations
+    attributes:
+      label: Submission confirmations
+      options:
+        - label: I have the right to submit all source, assets, names, and license information.
+          required: true
+        - label: The committed index sizes and SHA-256 values were calculated from the exact committed files.
+          required: true
+        - label: No credentials, personal data, trackers, obfuscated behavior, or undeclared network access are included.
+          required: true
+        - label: I read and followed docs/gallery.md and ran ./Scripts/release-readiness.sh.
+          required: true

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /Editor/editorfe
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      editor-development:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: swift
+    directory: /iOS
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: swift
+    directory: /macOS
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5

.github/pull_request_template.md

@@ -16,3 +16,10 @@ Describe the user-visible outcome and implementation scope.
 - [ ] No credentials or personal data are included
 - [ ] Script, network, import, iCloud, and app-group boundaries remain fail-closed
 - [ ] Migration or compatibility impact is documented
+
+## Gallery changes (when applicable)
+
+- [ ] Exact file byte counts and SHA-256 values match committed Gallery files
+- [ ] Source, author, license, permissions, network/privacy behavior, and update notes were reviewed
+- [ ] Widget family screenshots or Skill Prompt examples are attached
+- [ ] No arbitrary native/plugin execution or undeclared capability is introduced

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+Notable user-visible changes are recorded here. ScriptWidget follows semantic versioning for public package/runtime contracts even when App Store marketing versions use another cadence.
+
+## Unreleased
+
+### Added
+
+- Full macOS app and WidgetKit workspace with Studio editing, diagnostics, Console, multi-size previews, native commands, and first-run tutorial.
+- OpenAI-compatible Widget generation with Keychain-backed credentials, structured prompts, run/diagnose/refine workflow, evaluations, and reusable Skills 1.0.
+- Package 2.0 manifests, JSON schemas, migration compatibility, secure imports, and authoring documentation.
+- GitHub-backed Widget & Skills Gallery with verified files, offline cache, install/update UI on macOS and iOS/iPadOS, seed content, and contributor workflow.
+- Runtime XCTest targets, golden/template validation, release-readiness CI, and iPad/iCloud device scripts.
+
+### Changed
+
+- Expanded the template catalog to 70 validated examples and generated preview fixtures.
+- Reworked documentation around a five-minute path, versioned Runtime API, Studio, AI, Skills, packages, Gallery, release readiness, and bilingual onboarding.
+
+### Fixed
+
+- Added local build-cache fallback and proactive package caching for scripts evicted by iCloud. GitHub issue #6 remains open until the physical-iPhone offline acceptance matrix is complete.

CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Community Code of Conduct
+
+ScriptWidget is built by people with different backgrounds and levels of experience. We are committed to a welcoming, safe, and constructive community.
+
+## Expected behavior
+
+- Be respectful, patient, and specific. Critique ideas and code, not people.
+- Welcome beginners and explain assumptions without gatekeeping.
+- Respect privacy, licenses, authorship, and responsible security disclosure.
+- Accept feedback, correct mistakes, and prioritize the health of the community.
+- Keep discussions relevant and avoid harassment, threats, discrimination, sexualized attention, spam, or publishing another person's private information.
+
+## Enforcement
+
+Maintainers may edit or remove content, close participation, or temporarily or permanently ban contributors whose behavior harms the community. Enforcement should be proportional, documented privately when practical, and avoid exposing reporters or affected people.
+
+Report conduct concerns privately to `xnuapp@gmail.com`. Do not use a public issue for sensitive reports. Maintainers will review the available context, protect confidentiality as far as practical, and communicate the outcome to affected parties when appropriate.
+
+This policy applies in repository spaces and when someone publicly represents the ScriptWidget project.

CONTRIBUTING.md

@@ -2,6 +2,8 @@
 
 Thank you for helping make native widget creation accessible to everyone. Contributions to the runtime, ScriptWidget Studio, templates, tests, and documentation are welcome.
 
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). Maintainer roles and project decisions are described in [Governance](GOVERNANCE.md), current priorities in the [Roadmap](ROADMAP.md), and notable user-visible work in the [Changelog](CHANGELOG.md).
+
 ## Before you start
 
 - Search existing issues and discussions before opening a duplicate.

GOVERNANCE.md

@@ -0,0 +1,32 @@
+# Governance
+
+ScriptWidget uses a maintainer-led, contribution-friendly model. The goal is to make decisions transparent while keeping a security-sensitive Apple application coherent and shippable.
+
+## Roles
+
+- **Users** report needs, test releases, and share widgets or Skills.
+- **Contributors** submit code, tests, documentation, designs, templates, or reviews under the project license.
+- **Reviewers** are trusted contributors who consistently provide accurate review in a subsystem.
+- **Maintainers** merge changes, manage releases and security reports, curate Gallery content, and set repository policy. The current lead maintainer is Everett Jiang (`@everettjf`).
+
+Roles are earned through sustained, constructive work. Maintainers may delegate review areas and should document new maintainer or reviewer responsibilities publicly.
+
+## Decisions
+
+Routine fixes use pull-request review and passing release checks. Significant changes—public Runtime APIs, package formats, security boundaries, data collection, platform scope, large dependencies, or migrations—start with an issue or discussion describing the user problem, alternatives, compatibility, risk, tests, and documentation.
+
+Maintainers seek rough consensus, but the lead maintainer has final responsibility when a decision is blocked. Decisions should cite technical and user evidence; disagreement is not misconduct. Security fixes may be developed privately and documented after coordinated disclosure.
+
+## Compatibility and trust
+
+Runtime and package contracts are versioned. Breaking changes require an explicit migration path and release note. Imported scripts, network content, Gallery metadata, AI output, iCloud documents, app-group storage, and credentials are security boundaries and must fail closed.
+
+The Gallery is curated, not an unrestricted executable marketplace. Inclusion is discretionary and may be revoked for security, privacy, licensing, abandonment, misleading behavior, or repeated quality failures.
+
+## Releases
+
+A release candidate should pass `./Scripts/release-readiness.sh`, document known limitations, and complete the device matrix appropriate to its changes. Maintainers publish release notes from `CHANGELOG.md` and may defer a feature that cannot be verified safely.
+
+## Policy changes
+
+Governance changes use a pull request and normal public review. The lead maintainer may make an urgent temporary policy change for safety, followed by a documented review.

README.md

@@ -7,6 +7,7 @@
 [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-iOS%20%7C%20macOS-lightgrey?style=flat-square&logo=apple)](https://developer.apple.com)
 [![Version](https://img.shields.io/badge/Version-3.0-blue?style=flat-square)](https://github.com/everettjf/ScriptWidget/releases)
+[![Release Readiness](https://github.com/everettjf/ScriptWidget/actions/workflows/release-readiness.yml/badge.svg)](https://github.com/everettjf/ScriptWidget/actions/workflows/release-readiness.yml)
 
 **Create native widgets for iPhone, iPad, and Mac using JavaScript, JSX, and AI**
 
@@ -24,7 +25,7 @@ ScriptWidget is a powerful widget development platform that lets you create nati
 
 Think of it as "React Native for Widgets" - but simpler and more flexible.
 
-![ScriptWidget Demo](screenshot.png)
+![ScriptWidget template gallery](Resource/WidgetDemoScreenshots/_contact-sheet-1.jpg)
 
 ---
 
@@ -39,6 +40,7 @@ Think of it as "React Native for Widgets" - but simpler and more flexible.
 | 📱 **Interactive Widgets** | Tap, swipe, and interact with widgets |
 | 🎨 **Custom Styling** | Full control over appearance |
 | 📦 **Template Gallery** | Pre-built templates to get started |
+| 🌐 **Community Gallery** | Verified, one-click Widget and AI Skill installs |
 | 🧰 **ScriptWidget Studio** | Build on Mac with CodeMirror, diagnostics, console, and multi-size preview |
 | ✨ **AI Generation** | Generate, run, diagnose, and refine widgets with an OpenAI-compatible model |
 
@@ -80,6 +82,7 @@ ScriptWidget/
 ├── Shared/
 │   └── ScriptWidgetRuntime/   # Core runtime: JavaScriptCore host, JSX→SwiftUI
 │       ├── Common/            # Script storage & package management
+│       ├── Gallery/           # Verified GitHub catalog, cache & installer
 │       ├── Widget/Runtime/    # JS engine setup, Babel transform, execution
 │       ├── Widget/API/        # JS APIs ($device, $file, $storage, ...)
 │       ├── Widget/Component/  # Element → SwiftUI view mapping
@@ -92,6 +95,7 @@ ScriptWidget/
 │   ├── ScriptWidgetMac/       # macOS app
 │   └── ScriptWidgetMacWidget/ # macOS widget
 ├── Editor/editorfe/           # React + CodeMirror editor frontend
+├── Gallery/                   # Curated Widget & Skills Gallery index
 ├── Resource/                  # Marketing assets, screenshots
 └── README.md
 ```
@@ -216,7 +220,7 @@ Start with the **[documentation hub](docs/README.md)** or build **[your first wi
 
 <div align="center">
 
-![Widget Gallery](gallery.png)
+![Widget Gallery](Resource/WidgetDemoScreenshots/_contact-sheet-2.jpg)
 
 *Sample widgets created with ScriptWidget*
 
@@ -246,6 +250,9 @@ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md)
 - 🔧 Submit pull requests
 - 📝 Write documentation
 - 🎨 Share your widgets
+- 🧠 Share focused AI Skills
+
+See the [public roadmap](ROADMAP.md), [governance model](GOVERNANCE.md), and [Gallery submission guide](docs/gallery.md). Every pull request runs the same release-readiness checks used locally.
 
 ---
 

README_CN.md

@@ -0,0 +1,70 @@
+# ScriptWidget 🎨
+
+<div align="center">
+
+[![GitHub Stars](https://img.shields.io/github/stars/everettjf/ScriptWidget?style=flat-square&color=4ECDC4)](https://github.com/everettjf/ScriptWidget/stargazers)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+[![Release Readiness](https://github.com/everettjf/ScriptWidget/actions/workflows/release-readiness.yml/badge.svg)](https://github.com/everettjf/ScriptWidget/actions/workflows/release-readiness.yml)
+
+**使用 JavaScript、JSX 和 AI，为 iPhone、iPad 与 Mac 创建原生 Widget**
+
+[English](README.md) | [中文](README_CN.md)
+
+</div>
+
+![ScriptWidget 模板画廊](Resource/WidgetDemoScreenshots/_contact-sheet-1.jpg)
+
+ScriptWidget 是一个 MIT 开源的 Widget 创作平台。你不需要学习 Swift：在 Mac Studio、iPhone 或 iPad 上编辑 `main.jsx`，运行时会把声明式 JSX 映射为原生 SwiftUI/WidgetKit 界面。
+
+## 为什么选择 ScriptWidget
+
+- 一份脚本适配 iOS、iPadOS 与 macOS，多尺寸布局可通过 `$getenv("widget-size")` 调整。
+- 支持交互式 Widget、App Intents、Live Activity、灵动岛与 Control Widget。
+- Mac Studio 内置 CodeMirror 编辑器、补全、诊断、Console 和多尺寸预览。
+- 可用 OpenAI 兼容模型生成、运行、诊断并迭代 Widget；API Key 保存在 Keychain。
+- Widget & Skills Gallery 支持经过索引、大小、路径与 SHA-256 验证的一键安装和离线缓存。
+- 70 个内置模板、版本化 Runtime API、Package 2.0 与 Skills 1.0 均有自动测试和发布门禁。
+
+## 五分钟开始
+
+```bash
+git clone https://github.com/everettjf/ScriptWidget.git
+cd ScriptWidget
+open macOS/ScriptWidgetMac.xcodeproj
+# 或：open iOS/ScriptWidget.xcodeproj
+```
+
+在 Xcode 中选择 `ScriptWidgetMac` 或 `ScriptWidget` scheme，配置 `iCloud.ScriptWidget` container 与 `group.everettjf.scriptwidget` App Group，然后运行。也可以直接按照[五分钟教程](docs/five-minute-tutorial.md)创建第一个 Widget。
+
+最小脚本：
+
+```jsx
+$render(
+  <vstack frame="max" background="#0f172a">
+    <text font="title3" color="#f8fafc">Hello, ScriptWidget!</text>
+  </vstack>
+);
+```
+
+## 文档
+
+- [文档中心](docs/README.md)
+- [从零创建第一个 Widget](docs/getting-started.md)
+- [ScriptWidget Studio](docs/studio.md)
+- [Runtime API](docs/runtime-api.md)
+- [AI 生成](docs/ai-generate.md)
+- [Widget & Skills Gallery](docs/gallery.md)
+- [Package 2.0](docs/package-format.md) 与 [Skills 1.0](docs/skills.md)
+- [公开路线图](ROADMAP.md)
+
+## 参与贡献
+
+欢迎提交 Runtime、Mac/iOS 体验、模板、Gallery Widget、AI Skill、测试与文档。请先阅读[贡献指南](CONTRIBUTING.md)、[治理规则](GOVERNANCE.md)和[行为准则](CODE_OF_CONDUCT.md)，并在提交前运行：
+
+```bash
+./Scripts/release-readiness.sh
+```
+
+安全问题请按照[安全政策](SECURITY.md)私下报告，不要在公开 Issue 中披露利用细节或个人数据。
+
+ScriptWidget 使用 [MIT License](LICENSE) 发布。