fishandsheep · fishandsheep · Aug 6, 2026 · Aug 6, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Report a reproducible parser, routing, UI, or export problem
+title: "bug: "
+labels: needs-triage
+assignees: ""
+---
+
+## Summary
+
+<!-- Do not include unsanitized production configuration. -->
+
+## Reproduction
+
+1.
+2.
+3.
+
+## Expected behavior
+
+
+## Actual behavior
+
+
+## Environment
+
+- Release:
+- Browser and version:
+- Operating system:
+
+## Sanitized configuration or fixture
+
+<!-- Replace hostnames, addresses, credentials, certificates, tokens, and private paths. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an improvement to Nginx UI Topology
+title: "feat: "
+labels: needs-triage
+assignees: ""
+---
+
+## Problem
+
+
+## Proposed behavior
+
+
+## Nginx semantics involved
+
+<!-- Explain the relevant directive or routing behavior when applicable. -->
+
+## Alternatives considered
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,12 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - "release/**"
+  pull_request:
+
+jobs:
+  quality:
+    uses: ./.github/workflows/quality.yml
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -15,9 +15,13 @@ concurrency:
   group: pages
   cancel-in-progress: false
 
-jobs:
-  build:
-    runs-on: ubuntu-latest
+jobs:
+  quality:
+    uses: ./.github/workflows/quality.yml
+
+  build:
+    needs: quality
+    runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
@@ -32,11 +36,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run tests
-        run: npm test
-
-      - name: Build
-        run: npm run build
+      - name: Build
+        run: npm run build
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
@@ -0,0 +1,61 @@
+name: Quality
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  unit:
+    name: Unit, build, and audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+
+  e2e:
+    name: E2E (${{ matrix.browser }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        browser: [chromium, firefox, webkit]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps ${{ matrix.browser }}
+
+      - name: Run E2E tests
+        run: npm run test:e2e -- --project=${{ matrix.browser }}
diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,9 @@
 node_modules/
 dist/
 .vite/
-coverage/
-*.log
+coverage/
+test-results/
+*.log
 *.tsbuildinfo
 vite.config.js
 vite.config.d.ts

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues and specs live in GitHub Issues for `fishandsheep/ngui`; use `gh`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Use `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout: root `CONTEXT.md` and `docs/adr/`. See `docs/agents/domain.md`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0-beta.1] - 2026-08-06
+
+Initial public Beta release.
+
+- Visualize Nginx `http` and `stream` routing topology locally in the browser.
+- Inspect explainable route candidates, configuration issues, source locations, and confidence.
+- Export topology as versioned JSON or PNG.
+- Support Chinese and English interfaces, dark and light themes, and current desktop Chrome, Firefox, and Safari.
+
+This release does not claim to emulate complete Nginx runtime behavior. See the supported and unsupported concepts in the README.
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -0,0 +1,57 @@
+# Nginx UI Topology Context
+
+Nginx UI Topology helps operators and developers understand how an Nginx configuration may route requests. It turns a user-provided configuration snapshot into an explainable topology and diagnostic guidance while keeping the configuration in the browser.
+
+## Inputs and outputs
+
+**Configuration snapshot**:
+A user-provided `nginx -T` output or Nginx configuration text representing configuration at a point in time.
+_Avoid_: Live configuration, runtime state
+
+**Routing topology**:
+A visual representation of entry points, servers, routes, upstream groups, backend targets, variables, and their relationships derived from a configuration snapshot.
+_Avoid_: Runtime request trace, guaranteed execution graph
+
+**Route candidate**:
+A possible request path identified from the snapshot for a supplied host, path, protocol, and port.
+_Avoid_: Actual route, guaranteed route
+
+**Static inference**:
+An explainable conclusion derived from configuration text without executing Nginx or its modules.
+_Avoid_: Runtime simulation, configuration validation
+
+**Configuration issue**:
+A parser error, risky configuration pattern, or advisory observation tied to evidence in the snapshot.
+_Avoid_: Nginx error, production incident
+
+**Source location**:
+The file marker and line position in the snapshot that support a topology element, route candidate, or configuration issue.
+_Avoid_: Runtime stack trace
+
+**Confidence**:
+An indication of how directly a topology element or route candidate follows from known configuration syntax and semantics.
+_Avoid_: Probability, production guarantee
+
+**Local-only session**:
+A browser session in which configuration text, parsed results, and diagnostics remain on the user's device and are not uploaded or persisted as a configuration workspace.
+_Avoid_: Cloud workspace, remote backup
+
+**Topology export**:
+A versioned JSON representation of derived topology and diagnostics, or a rendered PNG, that the user explicitly downloads for sharing or record-keeping.
+_Avoid_: Configuration backup, live system snapshot
+
+## Product boundary
+
+**Supported Nginx subset**:
+Common `http` and `stream` routing concepts documented by the product, including servers, listeners, server names, locations, rewrites, returns, upstreams, common pass directives, and backend entries.
+_Avoid_: Full Nginx compatibility
+
+**Unsupported runtime behavior**:
+Lua, njs, third-party modules, complex dynamic behavior, include expansion, and other semantics that cannot be concluded reliably from the supplied text alone.
+_Avoid_: Broken configuration
+
+## Release language
+
+**Public Beta**:
+A publicly usable release whose documented behavior is valuable but whose supported Nginx subset and inference accuracy are still being validated against real configurations.
+_Avoid_: Stable release, production guarantee
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for helping improve Nginx UI Topology.
+
+## Development
+
+```bash
+npm ci
+npm run dev
+```
+
+Before opening a pull request, run:
+
+```bash
+npm test
+npm run test:e2e
+npm run build
+npm audit --audit-level=high
+```
+
+Install Playwright browsers locally when needed:
+
+```bash
+npx playwright install chromium firefox webkit
+```
+
+## Configuration data
+
+Never commit real production `nginx -T` output. Use sanitized fixtures with fake hostnames, addresses, credentials, certificates, tokens, and paths.
+
+## Pull requests
+
+- Explain the user-facing behavior and the supported Nginx semantics involved.
+- Add or update parser, routing, fixture, or browser tests for behavior changes.
+- Keep static inference explainable; do not present uncertain runtime behavior as a guaranteed result.
+- Update the bilingual README or changelog when release-facing behavior changes.
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,6 @@
-                                 Apache License
+Copyright 2026 fishandsheep
+
+                                 Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 

diff --git a/README-en.md b/README-en.md
@@ -4,14 +4,20 @@
 
 [中文文档](README.md)
 
+[Live demo](https://fishandsheep.github.io/ngui/) · [GitHub Issues](https://github.com/fishandsheep/ngui/issues)
+
 ![React](https://img.shields.io/badge/React-18-61dafb?logo=react&logoColor=111)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=fff)
-![Vite](https://img.shields.io/badge/Vite-5-646cff?logo=vite&logoColor=fff)
+![Vite](https://img.shields.io/badge/Vite-8-646cff?logo=vite&logoColor=fff)
 ![Local First](https://img.shields.io/badge/Privacy-local--first-22c55e)
 ![License](https://img.shields.io/badge/License-Apache--2.0-blue)
 
 Nginx UI Topology is a local-first web tool for visualizing nginx routing behavior. Paste or upload the output from `nginx -T`, then inspect servers, locations, upstreams, targets, variables, and request flow from an interactive topology canvas.
 
+## Beta status
+
+The current release is `v0.1.0-beta.1`. The first release targets current desktop Chrome, Firefox, and Safari versions. Its output is explainable static inference over the documented nginx subset, not an exact nginx runtime emulator.
+
 ## Screenshots
 
 ### Dark Mode
@@ -116,7 +122,14 @@ npm run preview  # preview the production build
 
 ## Privacy
 
-All parsing and rendering happens in the browser. The app does not require a backend service and does not upload nginx configuration content.
+All parsing and rendering happens in the browser. The app has no backend service, telemetry, or configuration persistence; only theme and language preferences may be stored in the browser. JSON exports include `schemaVersion: 1` and may contain hostnames, paths, and backend addresses, so review them before sharing.
+
+## Release and feedback
+
+- [Changelog](CHANGELOG.md)
+- [Security policy](SECURITY.md)
+- [Contributing guide](CONTRIBUTING.md)
+- Report issues through [GitHub Issues](https://github.com/fishandsheep/ngui/issues); do not submit unsanitized production configurations.
 
 ## License
 

diff --git a/README.md b/README.md
@@ -4,14 +4,20 @@
 
 [English](README-en.md)
 
+[在线体验](https://fishandsheep.github.io/ngui/) · [GitHub Issues](https://github.com/fishandsheep/ngui/issues)
+
 ![React](https://img.shields.io/badge/React-18-61dafb?logo=react&logoColor=111)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=fff)
-![Vite](https://img.shields.io/badge/Vite-5-646cff?logo=vite&logoColor=fff)
+![Vite](https://img.shields.io/badge/Vite-8-646cff?logo=vite&logoColor=fff)
 ![Local First](https://img.shields.io/badge/Privacy-local--first-22c55e)
 ![License](https://img.shields.io/badge/License-Apache--2.0-blue)
 
 Nginx UI Topology 是一个本地优先的 Web 工具，用于可视化 Nginx 路由行为。粘贴或上传 `nginx -T` 的输出，然后在交互式拓扑画布中查看服务器、location、upstream、后端目标、变量和请求流向。
 
+## Beta 状态
+
+当前发布版本为 `v0.1.0-beta.1`。首版面向桌面端最新版 Chrome、Firefox 和 Safari，输出是针对文档化 Nginx 子集的可解释静态推断，不是精确的 Nginx 运行时模拟器。
+
 ## 截图
 
 ### 深色模式
@@ -116,7 +122,14 @@ npm run preview  # 预览生产构建
 
 ## 隐私
 
-所有解析和渲染均在浏览器中完成。应用不需要后端服务，也不会上传 Nginx 配置内容。
+所有解析和渲染均在浏览器中完成。应用不需要后端服务，不使用遥测，也不会上传或持久化 Nginx 配置内容；仅主题和语言偏好会保存在浏览器中。JSON 导出包含 `schemaVersion: 1`，并可能包含主机名、路径和后端地址，分享前请先检查内容。
+
+## 发布与反馈
+
+- [变更记录](CHANGELOG.md)
+- [安全报告](SECURITY.md)
+- [贡献指南](CONTRIBUTING.md)
+- 请通过 [GitHub Issues](https://github.com/fishandsheep/ngui/issues) 反馈问题；不要提交未脱敏的生产配置。
 
 ## 许可证
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,15 @@
+# Security Policy
+
+## Scope
+
+Nginx UI Topology is a static browser application. It does not provide a backend, does not upload configuration text, and does not treat its static inference as a security control or a replacement for `nginx -t`.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting for this repository when available. If private reporting is unavailable, contact the repository maintainers through GitHub before opening a public issue.
+
+Do not include production configuration, credentials, private hostnames, certificates, tokens, or other sensitive data in a report. Provide a sanitized reproduction and the affected browser, release version, and steps to reproduce.
+
+## Supported versions
+
+Only the latest `v0.1.0-beta.*` release receives active release validation during the Beta period. Older builds may remain available on GitHub Pages history but are not a supported security baseline.