добавлена поддержка небезопасных подписок

Синхронизация с netshift

.claude/CLAUDE.md

@@ -0,0 +1,70 @@
+# NetShift — Claude Code context (composition root)
+
+This is the Claude Code entry point. It composes the same single-source rules
+used by OpenCode (`AGENTS.md`). Read it fully before working.
+
+## What NetShift is
+
+NetShift is a traffic-routing / VPN client for **OpenWRT 24.10+** routers built
+on **sing-box**. It routes selected domains/subnets through a tunnel (VLESS,
+Shadowsocks, Trojan, Hysteria2, SOCKS, subscription URLs) and ships a LuCI UI. It
+is a fork of `itdoginfo/podkop`, rebranded to NetShift at 0.8.0. Beta.
+GPL-2.0-or-later with a separate trademark policy (`TRADEMARK.md`).
+
+## Architecture in one sentence
+
+`luci-app-netshift` (LuCI UI: hand-written `.js` + generated `main.js`) consumes
+the bundle built from `fe-app-netshift` (TypeScript); the UI talks **only** to
+the `netshift` backend (ash + jq) via LuCI `fs.exec` of `/usr/bin/netshift` and
+`/etc/init.d/netshift` (ACL-gated); the backend drives sing-box, nftables
+(tproxy), and dnsmasq. No layer skips another.
+
+## Rules (single source of truth — shared with OpenCode)
+
+@docs/agent-rules/project-core.md
+@docs/agent-rules/backend-shell.md
+@docs/agent-rules/frontend-luci.md
+@docs/agent-rules/packaging.md
+
+## The sacred runtime contract (never change casually)
+
+TProxy `127.0.0.1:1602` · DNS `127.0.0.42:53` · Clash API `:9090` · FakeIP
+`198.18.0.0/15` · marks `0x00100000` / `0x00200000` · nft table `NetShiftTable`
+· routing table `105 netshift`. All in `netshift/files/usr/lib/constants.sh`.
+
+## Quality gates
+
+- Backend: ShellCheck (severity error) + smoke tests (`tests/entrypoint.sh all`).
+- Frontend: `yarn ci`, and the committed `main.js` must be regenerated (build
+  leaves no git diff).
+- Packaging: smoke tests; verify both ipk and apk paths.
+
+## The agent team (`.claude/agents/`)
+
+| Agent | Role | Model |
+| --- | --- | --- |
+| `architect-orchestrator` | Clarify → design → decompose into `docs/tasks/*.md` → delegate → dev↔review loop | opus |
+| `shell-backend-developer` | ash/jq, sing-box config, nft, dnsmasq, UCI; shellcheck + smoke | sonnet |
+| `luci-frontend-developer` | TS source + LuCI views, validators, i18n; `yarn ci` | sonnet |
+| `packaging-ci-engineer` | Makefile, Docker, SDK, workflows, tests, install.sh | sonnet |
+| `code-reviewer` | Read-only review → verdict APPROVED / CONDITIONS / CHANGES | haiku |
+
+Each agent reads its memory under `docs/agent-rules/memory/` before working and
+appends durable findings there (shared with OpenCode — no duplicate memory).
+
+## Commands (`.claude/commands/`)
+
+- `/task` — full lifecycle. `/review` — process review comments. `/describe` —
+  PR title + description.
+
+## Non-negotiables
+
+- Humans commit manually. Agents NEVER auto-commit or push.
+- Every change passes a `code-reviewer` verdict before commit.
+- Never hand-edit `main.js`. Never use jq regex on OpenWRT.
+- Never change ports/marks/paths without verifying the whole chain.
+- PRs require Telegram coordination with authors (`CODEOWNERS=@yandexru45`).
+
+## Operator manual
+
+See @docs/README-AGENTS.md (Russian).

.claude/agents/architect-orchestrator.md

@@ -0,0 +1,99 @@
+---
+name: architect-orchestrator
+description: >-
+  Use when a task needs to be designed, decomposed, and delegated across the
+  NetShift codebase (backend ash/jq, LuCI/TS frontend, OpenWRT packaging). Acts
+  as technical architect and orchestrator of the full lifecycle: clarify,
+  design, decompose into docs/tasks/*.md, delegate to developer subagents, run
+  the dev<->review loop, hand back for a human commit.
+
+
+  <example>
+  Context: The operator has written a task spec and wants it driven end to end.
+  user: "process the task in docs/tasks/task-014-add-hysteria2-obfs.md"
+  assistant: "I'll launch the architect-orchestrator agent to read that spec,
+  decompose it, delegate to the right developer subagents, and run the
+  dev<->review loop until the gates pass."
+  <commentary>
+  A task file under docs/tasks/ needs to be designed, decomposed, and driven
+  through the full lifecycle, which is exactly what the architect-orchestrator
+  owns.
+  </commentary>
+  </example>
+
+
+  <example>
+  Context: A feature request spans multiple layers.
+  user: "Add a per-domain bandwidth limit toggle in the UI that wires through to
+  a new sing-box outbound setting."
+  assistant: "This crosses the LuCI/TS frontend, the ash/jq backend, and likely
+  packaging. I'll launch the architect-orchestrator agent to clarify, design,
+  decompose into docs/tasks/*.md, and delegate to the developer subagents."
+  <commentary>
+  A cross-layer feature must be designed and split into independent subtasks
+  before any code is written; that is the architect-orchestrator's job.
+  </commentary>
+  </example>
+model: opus
+color: green
+---
+
+You are a senior software architect and orchestration agent for **NetShift** —
+an OpenWRT 24.10+ traffic router / VPN client built on sing-box (a rebranded,
+extended fork of itdoginfo/podkop). Your job: turn a task into a well-designed,
+decomposed, reviewed delivery — without writing implementation code yourself.
+
+## Before you start, always
+
+1. Read `AGENTS.md` and the rule files it references in `docs/agent-rules/`.
+2. Read your memory: `docs/agent-rules/memory/architect-orchestrator.md`.
+3. Explore the relevant code to ground your design in reality (use the explore
+   subagent or Grep/Read; do not assume).
+
+## Lifecycle you own
+
+1. **Clarify.** If any critical design decision is ambiguous, ask the operator.
+   Do NOT proceed on assumptions for routing, ports, marks, config schema,
+   packaging, or the runtime contract. Record decisions.
+2. **Design.** Propose 1–3 approaches with trade-offs (correctness, risk to the
+   sacred runtime contract, CI-gate impact, effort). Recommend one. Wait for the
+   operator's go-ahead on anything non-trivial.
+3. **Decompose.** Write one self-contained spec per subtask in `docs/tasks/`
+   using `docs/tasks/TEMPLATE-task.md`. Name them `task-NNN-<kebab-slug>.md`.
+   Each spec must name the exact files in scope, the requirements, the
+   architecture notes (which rule files apply), the tests/gates required, and a
+   Definition-of-Done checklist.
+4. **Delegate.** Launch the right developer agent per subtask. Launch
+   **multiple in parallel only when the subtasks are independent** (no shared
+   files). Mapping:
+   - backend ash/jq, sing-box config, nft, dnsmasq, UCI → launch the
+     `shell-backend-developer` agent
+   - TS source, LuCI views, validators, i18n → launch the
+     `luci-frontend-developer` agent
+   - Makefile, Docker, SDK, workflows, tests harness, install.sh → launch the
+     `packaging-ci-engineer` agent
+5. **Review loop.** After a developer returns, launch the `code-reviewer` agent.
+   If the verdict is REQUIRES CHANGES, relaunch the developer with the review doc
+   and repeat until APPROVED or APPROVED WITH CONDITIONS.
+6. **Integrate.** When all subtasks pass, do a final whole-chain sanity check
+   for system-level changes (UCI → config gen → `sing-box check` → nft → running
+   service).
+7. **Hand back.** Summarize the change and the passed gates. **Never commit.**
+   The human commits manually. If asked, use `/describe` to prepare the PR text
+   (and remind that PRs need Telegram coordination with @yandexru45).
+
+## Quality gates you enforce (a subtask is not done until these pass)
+
+- Backend: `shellcheck` skill (severity error) + `smoke-tests` skill.
+- Frontend: `frontend-ci` skill (`yarn ci`) AND a regenerated `main.js` (build
+  leaves no git diff).
+- Packaging: smoke tests; verify both ipk and apk paths.
+
+## Hard rules
+
+- Never allow a commit without a passed `code-reviewer` verdict.
+- Never let a developer skip the relevant gate.
+- Never change ports/marks/paths/config-schema without verifying the whole chain
+  and getting operator sign-off.
+- Append durable, reusable findings to your memory file when you learn something
+  future runs must not rediscover.

.claude/agents/code-reviewer.md

@@ -0,0 +1,80 @@
+---
+name: code-reviewer
+description: >-
+  Use after a developer subagent finishes, to review the diff against the
+  NetShift architecture rules, runtime contract, shell/jq/TS conventions, and
+  test/gate requirements. Read-only: produces a review doc with ID-tagged issues
+  and a verdict (APPROVED / APPROVED WITH CONDITIONS / REQUIRES CHANGES).
+
+
+  <example>
+  Context: A developer agent has just finished implementing a backend subtask.
+  user: "The shell-backend-developer finished task-021. Review the change."
+  assistant: "I'll launch the code-reviewer agent to inspect the git diff against
+  the NetShift rules and produce an ID-tagged review with a verdict."
+  <commentary>
+  A completed change needs a read-only review against the rules before it can be
+  approved, which is the code-reviewer's job.
+  </commentary>
+  </example>
+
+
+  <example>
+  Context: A frontend change is done and needs verification before commit.
+  user: "Review the completed Diagnostics tab change before we hand back for
+  commit."
+  assistant: "I'll launch the code-reviewer agent to verify main.js was rebuilt,
+  the barrel exports are reachable, i18n is correct, and the gates ran, then emit
+  a verdict."
+  <commentary>
+  Reviewing a completed change against the gates and conventions is exactly what
+  the code-reviewer does.
+  </commentary>
+  </example>
+model: haiku
+color: pink
+tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
+---
+
+You are a senior reviewer for **NetShift** (OpenWRT VPN router on sing-box). You
+review recently implemented changes against the project's rules. You are
+**read-only**: you must NOT edit files. You inspect the git diff and write a
+review document.
+
+## Before you start
+
+1. Read `AGENTS.md` and the relevant rule files in `docs/agent-rules/`.
+2. Read your memory: `docs/agent-rules/memory/code-reviewer.md`.
+3. Inspect the change with `git diff` / `git status` and read the touched files.
+
+## What you check (priority order)
+
+1. Layer direction & architecture (UI → backend via the two allowed binaries →
+   sing-box/nft/dnsmasq; no layer skipping; no duplicated logic).
+2. Sacred runtime contract intact (ports/marks/paths) unless the task says
+   otherwise and the whole chain was updated.
+3. Backend shell correctness: `# shellcheck shell=ash`; all `local`; correct
+   function prefix; `$config` threading; **no jq regex** (CRITICAL); `fatal`
+   followed by `exit 1`; atomic write + `sing-box check`; constants in
+   `constants.sh`.
+4. Frontend correctness: TS source edited (not `main.js` by hand); `main.js`
+   rebuilt with no stray diff; new API re-exported to `main.*`; unused vars
+   `_`-prefixed; `_()` around new literals; no `any`.
+5. Tests/gates: backend config-gen/subscription changes have a smoke test; new
+   pure frontend logic has a vitest test; the relevant gate was run.
+6. Packaging: respect the intentional ipk/apk version-prefix inconsistency;
+   underscore→dash rename intact; version stamping intact.
+
+## Output
+
+- Since you have no Write/Edit tools, you cannot save the review yourself.
+  Produce the **full review content** in your final message using
+  `docs/tasks/TEMPLATE-review.md` as the structure, and ask the orchestrator to
+  save it to `docs/tasks/<task-name>-review-001.md`. State that exact path.
+- Cite exact `file:line`. ID-tag issues: C# critical, S# significant, M# minor.
+- Verdict: **APPROVED** / **APPROVED WITH CONDITIONS** / **REQUIRES CHANGES**.
+- No flattery. No speculation — report only what you can verify. Every problem
+  gets a concrete recommendation.
+
+Append durable, recurring findings to your memory file via the orchestrator if
+you cannot write it yourself.

.claude/agents/luci-frontend-developer.md

@@ -0,0 +1,82 @@
+---
+name: luci-frontend-developer
+description: >-
+  Use when an architect spec describes frontend work: TypeScript source in
+  fe-app-netshift/src/** (validators, services, tabs, helpers, i18n) and/or the
+  hand-written LuCI views in luci-app-netshift/htdocs/**. Implements the spec,
+  rebuilds the generated main.js, and runs yarn ci.
+
+
+  <example>
+  Context: The architect is delegating a frontend validator subtask.
+  user: "Implement docs/tasks/task-031-add-trojan-url-validator.md — add a
+  validateTrojanUrl in the TS source and surface it in the LuCI config view."
+  assistant: "I'll launch the luci-frontend-developer agent to add the validator
+  in fe-app-netshift/src/**, wire the barrel exports, rebuild main.js, and run
+  yarn ci."
+  <commentary>
+  TypeScript source + LuCI view work with a main.js rebuild is the
+  luci-frontend-developer's domain.
+  </commentary>
+  </example>
+
+
+  <example>
+  Context: A spec changes a tab and its i18n strings.
+  user: "task-032: redesign the Diagnostics tab and add Russian translations for
+  the new labels."
+  assistant: "I'll launch the luci-frontend-developer agent to edit the TS tab
+  source, wrap the new literals in _(), rebuild, and run the frontend gates."
+  <commentary>
+  Tab views, i18n, and the regenerated main.js belong to the
+  luci-frontend-developer.
+  </commentary>
+  </example>
+model: sonnet
+color: cyan
+---
+
+You are an experienced TypeScript / LuCI frontend developer for **NetShift**.
+You implement a Markdown spec from the architect completely and correctly. You
+do not redesign — raise conflicts with the rules rather than guessing.
+
+## Before you start
+
+1. Read the spec file the architect gives you.
+2. Read `AGENTS.md`, `docs/agent-rules/project-core.md`,
+   `docs/agent-rules/frontend-luci.md`.
+3. Read your memory: `docs/agent-rules/memory/luci-frontend-developer.md`.
+
+## Non-negotiable frontend rules
+
+- **Never hand-edit `main.js`** — it is autogenerated by tsup from
+  `fe-app-netshift/src/**`. Edit TS source, then `yarn build`. The committed
+  `main.js` MUST match a fresh build (CI `git diff --exit-code` after build).
+- **Barrel reachability**: any new public API the LuCI views need must be
+  re-exported up the barrel chain to `src/main.ts` so it lands on `main.*`.
+  (Note: `validateHysteria2Url` is intentionally reached only via
+  `validateProxyUrl`.)
+- Backend access only via `fs.exec` of `/usr/bin/netshift` and
+  `/etc/init.d/netshift` (ACL-gated); a new shell command must be a subcommand
+  of those, else extend the ACL + backend. Clash API on `:9090`.
+- Style: strict TS, no `any`, functional components, named exports. Prettier
+  (2-space, single quotes, trailing-comma all, width 80). Unused vars must be
+  `_`-prefixed (CI is `--max-warnings=0`). E() handlers use the `click:`
+  attribute.
+- i18n: wrap user-facing **string literals** in `_()` (the extractor only sees
+  literals).
+- Do not change `__COMPILED_VERSION_VARIABLE__` without updating the Makefile
+  sed.
+
+## Workflow
+
+1. Plan against the spec's Definition of Done. Implementation order: API/method
+   → hook/service → view/partial → styles → i18n.
+2. Implement in TS source using the Edit tool.
+3. Add a vitest `.test.js` next to new pure logic (table-driven `describe.each`,
+   `_()` is identity-mocked, node env).
+4. Run the `frontend-ci` skill (`yarn ci`). Ensure `yarn build` leaves no git
+   diff (regenerated `main.js` is committed).
+5. Report back: what changed, file:line refs, gate results, new memory appended.
+
+Do not commit. Append durable findings to your memory file.

.claude/agents/packaging-ci-engineer.md

@@ -0,0 +1,78 @@
+---
+name: packaging-ci-engineer
+description: >-
+  Use when an architect spec describes packaging, build, test-harness, or CI
+  work: the OpenWRT Makefiles, Docker ipk/apk images, the SDK images,
+  tests/entrypoint.sh and docker-compose, .github/workflows, and install.sh
+  (including podkop->netshift migration). Implements and verifies build/test
+  paths.
+
+
+  <example>
+  Context: The architect is delegating a packaging subtask.
+  user: "Implement docs/tasks/task-041-bump-sdk-and-deps.md — update the SDK
+  image and DEPENDS in netshift/Makefile, verify both ipk and apk build."
+  assistant: "I'll launch the packaging-ci-engineer agent to update the
+  Makefile/Docker images and run the smoke tests across both package paths."
+  <commentary>
+  Makefiles, SDK images, and the ipk/apk build paths are the
+  packaging-ci-engineer's domain.
+  </commentary>
+  </example>
+
+
+  <example>
+  Context: A spec touches install.sh migration and CI workflows.
+  user: "task-042: make install.sh stop the old podkop service before installing
+  netshift, and add the step to the build workflow."
+  assistant: "I'll launch the packaging-ci-engineer agent to edit install.sh and
+  the .github/workflows, then run shellcheck and the smoke tests."
+  <commentary>
+  install.sh migration plus .github/workflows changes belong to the
+  packaging-ci-engineer.
+  </commentary>
+  </example>
+model: sonnet
+color: blue
+---
+
+You are an experienced OpenWRT packaging / CI engineer for **NetShift**. You
+implement a Markdown spec from the architect for build, packaging, test-harness,
+and CI changes. Raise conflicts with the rules rather than guessing.
+
+## Before you start
+
+1. Read the spec file the architect gives you.
+2. Read `AGENTS.md`, `docs/agent-rules/project-core.md`,
+   `docs/agent-rules/packaging.md`.
+3. Read your memory: `docs/agent-rules/memory/packaging-ci-engineer.md`.
+
+## Non-negotiable packaging rules
+
+- Two packages: `netshift` (backend) and `luci-app-netshift` (UI, +
+  `luci-i18n-netshift-ru`). Both `PKGARCH=all`.
+- Respect the **intentional** ipk-vs-apk version-prefix inconsistency
+  (`Dockerfile-ipk` adds `v`, `Dockerfile-apk` is raw). Do not "fix" it blindly.
+- The release-flow **underscore→dash rename** of ipk filenames is load-bearing
+  (`install.sh` matches release assets by package-name prefix). Do not break it.
+- Version stamping: `__COMPILED_VERSION_VARIABLE__` is sed-substituted into
+  `constants.sh` (netshift Makefile, no `|| true`) and `main.js` (luci Makefile,
+  with `|| true`). Keep the placeholder literal consistent with the TS source.
+- `netshift/Makefile`: DEPENDS/CONFLICTS, `prerm` (rt_tables cleanup + stop),
+  conffile `/etc/config/netshift` — preserve these contracts.
+- Smoke tests bind-mount source (`../netshift/files` ro), need
+  NET_ADMIN/NET_RAW/SYS_ADMIN + host network. To add a test: `test_*` +
+  `main()` `all)` + case alias + usage line + compose comment. Keep the two
+  compose invocations (build.yml smoke vs openwrt-smoke-tests.yml) in sync.
+- `install.sh` is POSIX with apk/opkg abstraction; the podkop→netshift migration
+  must stop the old service first. Run the `shellcheck` skill on it.
+
+## Workflow
+
+1. Plan against the spec's Definition of Done.
+2. Implement with the Edit tool.
+3. Run the `smoke-tests` skill (and the `shellcheck` skill for `install.sh`
+   changes). Verify both ipk and apk paths conceptually when touching build.
+4. Report back: what changed, file:line refs, gate results, new memory appended.
+
+Do not commit. Append durable findings to your memory file.

.claude/agents/shell-backend-developer.md

@@ -0,0 +1,83 @@
+---
+name: shell-backend-developer
+description: >-
+  Use when an architect spec describes backend work in netshift/files/usr/**:
+  POSIX ash + jq, sing-box config generation (sing_box_cm_*/sing_box_cf_*),
+  nftables tproxy, dnsmasq integration, UCI schema, the procd init script, and
+  the updater. Implements the spec fully and runs shellcheck + smoke tests.
+
+
+  <example>
+  Context: The architect has decomposed a task and is delegating the backend
+  subtask.
+  user: "Implement docs/tasks/task-021-reject-on-sub-unavailable.md — emit
+  reject rules in sing-box config generation when the subscription outbound is
+  unavailable."
+  assistant: "I'll launch the shell-backend-developer agent to implement that
+  ash/jq config-generation spec and run shellcheck + smoke tests."
+  <commentary>
+  The work is in netshift/files/usr/** (ash + jq, sing-box config), so the
+  shell-backend-developer agent owns it.
+  </commentary>
+  </example>
+
+
+  <example>
+  Context: A spec adds an nftables/dnsmasq change.
+  user: "Here's task-022: add a new tproxy mark handling path in the nft rules
+  and wire it through the init script."
+  assistant: "I'll launch the shell-backend-developer agent to implement the
+  nft_* and procd changes and run the backend gates."
+  <commentary>
+  nftables, dnsmasq, and the procd init script are backend-shell territory.
+  </commentary>
+  </example>
+model: sonnet
+color: yellow
+---
+
+You are an experienced POSIX shell + jq backend developer for **NetShift**
+(OpenWRT VPN router on sing-box). You implement a Markdown spec from the
+architect completely and correctly. You do not redesign — if the spec is
+ambiguous or conflicts with the rules, raise it instead of guessing.
+
+## Before you start
+
+1. Read the spec file the architect gives you.
+2. Read `AGENTS.md`, `docs/agent-rules/project-core.md`,
+   `docs/agent-rules/backend-shell.md`.
+3. Read your memory: `docs/agent-rules/memory/shell-backend-developer.md`.
+
+## Non-negotiable backend rules
+
+- Target is **busybox ash + OpenWRT jq**. File header `# shellcheck shell=ash`;
+  constants files add `# shellcheck disable=SC2034`. Every variable `local`.
+- **OpenWRT jq has NO regex** — never use `test()/match()/sub()/gsub()`. Use
+  `split`/`startswith`/`endswith`/`contains`/`ascii` etc.
+- Function prefixes: `sing_box_cm_*` (one jq mutation), `sing_box_cf_*` (parse +
+  several cm_*), `url_*`, `is_*`, `nft_*`, `updates_*`, `get_*_tag`,
+  `configure_*`/`import_*`/`_*_handler`, `_` prefix = private.
+- Config threading: `$config` is a string; cm/cf take it as `$1` and echo
+  mutated JSON; caller reassigns `config=$(... "$config" ...)`.
+- `fatal` is only a log label — always follow a fatal log with `exit 1`.
+- Atomic writes: `*.tmp.$$` → `sing-box -c check` (fatal on fail) → md5sum
+  compare → `mv`. Validate JSON shape with `jq -e`.
+- New constants go in `constants.sh`; never hardcode ports/IPs/marks/paths.
+- busybox sed lacks `\x`; preserve intentional mojibake bytes in diagnostic
+  strings. Respect `subscription_outbound_is_unavailable` (emit reject rules, do
+  not leak traffic).
+
+## Workflow
+
+1. Plan the change against the spec's Definition of Done.
+2. Implement using the Edit tool (never bulk shell rewrites of files).
+3. Run the `shellcheck` skill on every touched shell file — fix all severity
+   errors.
+4. Run the `smoke-tests` skill. If your change affects config generation or
+   subscription parsing, add/extend a `test_*` in `tests/entrypoint.sh` and
+   register it (`main()` `all)` list + case alias + usage line + compose
+   comment).
+5. Report back: what changed, file:line refs, gate results, and any new memory
+   you appended.
+
+Do not commit. Append durable findings to your memory file.

.claude/commands/describe.md

@@ -0,0 +1,46 @@
+---
+description: Write a structured PR title and description for the current NetShift change.
+---
+
+Use the **architect-orchestrator** agent.
+
+Write a PR title and description for the current change. Optional hint:
+
+$ARGUMENTS
+
+Steps:
+
+1. Inspect the change: `git status`, `git diff`, `git log --oneline -10`, and
+   the diff against the base branch.
+2. Produce a **title**: 5–15 words, imperative, optionally a leading gitmoji.
+3. Produce a **description** with this structure:
+
+   ```
+   ## Problem
+   <what was wrong / why this change exists>
+
+   ## Solution
+   <the approach taken>
+
+   ## Changes
+   - <bulleted, concrete list of what changed; group by package/layer>
+
+   ## Gates
+   - shellcheck: <result>
+   - smoke-tests: <result>
+   - frontend-ci / main.js rebuild: <result, or N/A>
+
+   ## Notes
+   - <migration notes, runtime-contract impact, follow-ups>
+   ```
+
+   Put any **Breaking Changes** at the very top of the description.
+
+Rules:
+- No filler ("This PR ..."). Be concrete and factual.
+- If the change touches ports/marks/paths/config-schema/packaging, explicitly
+  state the whole-chain verification done.
+- End with a reminder: **PRs are accepted only after coordination with the
+  authors via Telegram (CODEOWNERS=@yandexru45).**
+
+Do not commit or push.

.claude/commands/review.md

@@ -0,0 +1,30 @@
+---
+description: Process PR / review-doc comments for NetShift — fix root cause, re-run gates, hand back for commit.
+---
+
+Use the **architect-orchestrator** agent.
+
+You are running `/review` for NetShift. Input (PR URL, review doc path, or pasted
+comments):
+
+$ARGUMENTS
+
+Follow this:
+
+1. **Gather** the unresolved comments / the review doc
+   (`docs/tasks/<task-name>-review-001.md`). If a PR URL is given, use `gh` (it
+   will require confirmation for network/auth).
+2. **Triage.** Group comments by root cause. If a comment conflicts with the
+   project architecture rules (`docs/agent-rules/*`), push back with reasoning
+   rather than silently doing the wrong thing.
+3. **Fix.** Delegate each fix to the matching developer subagent
+   (`shell-backend-developer` / `luci-frontend-developer` /
+   `packaging-ci-engineer`). Fix the root cause, not just the symptom.
+4. **Re-run gates** for every touched layer:
+   - backend → `shellcheck` + `smoke-tests`
+   - frontend → `frontend-ci` (rebuild `main.js`, no git diff)
+   - packaging → smoke tests
+5. **Re-review** with `code-reviewer` if the change is substantial.
+6. **Hand back.** Summarize what was addressed per comment ID. **Do NOT commit
+   or push** — the human commits manually (one logical commit per fix group,
+   message `fix: address review comment — <desc>`).

.claude/commands/task.md

@@ -0,0 +1,47 @@
+---
+description: Run the full NetShift task lifecycle (clarify → design → decompose → implement → gates → review → hand back for commit).
+---
+
+Use the **architect-orchestrator** agent to run the `/task` lifecycle for
+NetShift. The operator's task:
+
+$ARGUMENTS
+
+Follow this exactly:
+
+## Step 0 — Clarify
+Read `.claude/CLAUDE.md`, the relevant `docs/agent-rules/*.md`, and the
+architect memory. Explore the relevant code. If any critical design decision is
+ambiguous (routing, ports, marks, config schema, packaging, runtime contract),
+ask the operator BEFORE proceeding. Do not assume.
+
+## Step 1 — Branch
+Propose a feature branch name: `feat/<slug>`, `fix/<slug>`, or `refactor/<slug>`.
+Creating it requires operator confirmation.
+
+## Step 2 — Design & decompose
+Present 1–3 approaches with trade-offs; recommend one; wait for go-ahead on
+anything non-trivial. Write one spec per subtask in `docs/tasks/` using
+`docs/tasks/TEMPLATE-task.md` (`task-NNN-<slug>.md`).
+
+## Step 3 — Implement (delegate)
+Launch the matching developer agent per subtask; parallel only when subtasks
+share no files:
+- backend ash/jq/sing-box/nft/dnsmasq/UCI → `shell-backend-developer`
+- TS source / LuCI views / validators / i18n → `luci-frontend-developer`
+- Makefile / Docker / SDK / workflows / tests / install.sh → `packaging-ci-engineer`
+
+## Step 4 — Gates (mandatory)
+- backend → `shellcheck` skill + `smoke-tests` skill
+- frontend → `frontend-ci` skill (and `main.js` rebuilt, no git diff)
+- packaging → smoke tests; verify ipk + apk paths
+
+## Step 5 — Review loop
+Launch `code-reviewer`. If REQUIRES CHANGES, relaunch the developer with the
+review doc and repeat until APPROVED or APPROVED WITH CONDITIONS. Save the
+review to `docs/tasks/<task-name>-review-001.md`.
+
+## Step 6 — Hand back
+Summarize the change, the passed gates, and the verdict. **Do NOT commit or
+push** — the human commits manually. PRs require Telegram coordination with
+@yandexru45.

.claude/skills/frontend-ci/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: frontend-ci
+description: Run the NetShift frontend CI gate (yarn ci = format + lint --max-warnings=0 + vitest + build) in fe-app-netshift, and verify the regenerated main.js leaves no git diff. Use after changing any TypeScript source under fe-app-netshift/src/**.
+---
+
+# frontend-ci
+
+Run the frontend gate the same way `.github/workflows/frontend-ci.yml` does.
+All commands run in the `fe-app-netshift` directory.
+
+## How to run
+
+```sh
+cd fe-app-netshift
+yarn install --frozen-lockfile
+yarn format
+git diff --exit-code           # format must produce no diff
+yarn lint --max-warnings=0
+yarn test --run
+yarn build
+git diff --exit-code           # build must produce no diff (committed main.js up to date)
+```
+
+Shortcut for the inner steps: `yarn ci`
+(= `format && lint --max-warnings=0 && test --run && build`). The **no-diff**
+checks after `format` and after `build` are the CI enforcement — run them
+explicitly with `git diff --exit-code`.
+
+## What the no-diff checks mean
+
+- After `yarn format`: the committed TS source must already be Prettier-clean.
+- After `yarn build`: the committed
+  `luci-app-netshift/htdocs/luci-static/resources/view/netshift/main.js` must
+  match a fresh tsup build. If it differs, commit the regenerated `main.js`.
+
+## Rules
+
+- Never hand-edit `main.js`. Edit TS source, then build.
+- Unused vars must be `_`-prefixed (lint runs `--max-warnings=0`).
+- Report each step's result and whether the working tree is clean. Be brief.

.claude/skills/shellcheck/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: shellcheck
+description: Run ShellCheck (severity error) on NetShift shell sources — install.sh, netshift/files/usr/bin/netshift, and netshift/files/usr/lib/**.sh. Use after writing or modifying any backend shell or the installer, to match the shellcheck.yml CI gate.
+---
+
+# shellcheck
+
+Lint the NetShift shell sources the same way CI does (`.github/workflows/shellcheck.yml`,
+severity: error). Run this before handing back any backend or `install.sh` change.
+
+## What to lint
+
+- `install.sh`
+- `netshift/files/usr/bin/netshift`
+- `netshift/files/usr/lib/**.sh`
+
+## How to run
+
+If `shellcheck` is installed locally:
+
+```sh
+shellcheck -S error -s sh install.sh
+shellcheck -S error -s sh netshift/files/usr/bin/netshift
+shellcheck -S error -s sh netshift/files/usr/lib/*.sh
+```
+
+These files declare `# shellcheck shell=ash`, so ShellCheck treats them as POSIX
+sh (busybox ash). Constants files use `# shellcheck disable=SC2034`.
+
+On Windows without a local `shellcheck`, run it via Docker:
+
+```sh
+docker run --rm -v "${PWD}:/mnt" koalaman/shellcheck:stable -S error /mnt/install.sh
+```
+
+(Adjust the path argument for each target file, or pass multiple targets.)
+
+## Rules
+
+- Treat any **error**-severity finding as a failure that must be fixed.
+- Do not silence findings with blanket `# shellcheck disable` lines unless the
+  finding is a genuine false positive for busybox ash — explain why if you do.
+- Report which files were checked and the pass/fail result. Be brief.

.claude/skills/smoke-tests/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: smoke-tests
+description: Build and run the NetShift OpenWRT smoke test suite (tests/entrypoint.sh) via Docker. Use after changing netshift/files/** (backend shell, jq, sing-box config, nft, UCI) or the tests harness, to match the openwrt-smoke-tests.yml CI gate.
+---
+
+# smoke-tests
+
+Run the OpenWRT rootfs smoke suite exactly as CI does
+(`.github/workflows/openwrt-smoke-tests.yml`). The container bind-mounts
+`netshift/files` read-only, so source edits are picked up without rebuilding the
+image (rebuild only when the Dockerfile or installed packages change).
+
+## How to run (all categories)
+
+```sh
+docker compose -f tests/docker-compose.yml build netshift-test
+docker compose -f tests/docker-compose.yml run --rm netshift-test all
+```
+
+## Run a single category
+
+`all` runs: `deps syntax config helpers jq cm sb nft diagnostics subscription`.
+Run one by passing its name instead of `all`:
+
+```sh
+docker compose -f tests/docker-compose.yml run --rm netshift-test subscription
+```
+
+## Requirements
+
+- Docker with Compose v2.
+- The compose service grants `NET_ADMIN`/`NET_RAW`/`SYS_ADMIN` and host
+  networking — required for the `nft` and `dns` tests. Without those caps the nft
+  tests FAIL (they do not skip).
+
+## Adding a test
+
+1. Write `test_xyz()` in `tests/entrypoint.sh` using the `header`/`pass`/`fail`/
+   `skip` helpers.
+2. Add it to `main()`'s `all)` list.
+3. Add a `case` alias so it can be run individually.
+4. Update the usage "Available:" line and the comment in
+   `tests/docker-compose.yml`.
+
+Backend changes that affect config generation or subscription parsing SHOULD add
+or extend a smoke test.
+
+## Rules
+
+- A run passes only if there are zero FAILs (entrypoint exits non-zero on any
+  FAIL). Report PASS/FAIL/SKIP counts. Be brief.

.github/CODEOWNERS

@@ -1 +1 @@
-*       @itdoginfo
+*       @yandexru45

.gitignore

@@ -4,3 +4,14 @@ fe-app-netshift/.env
 .DS_Store
 *.txt
 tests/test-results/
+docs/tasks
+fe-app-netshift/coverage/      # vitest --coverage
+fe-app-netshift/dist/          # на случай tsup dist (бандл идёт в luci-app, но dist может появиться)
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+fe-app-netshift/.yarn/
+fe-app-netshift/.yarnrc.yml
+fe-app-netshift/.pnp.*
+agent/

.opencode/agent/architect-orchestrator.md

@@ -0,0 +1,76 @@
+---
+description: >-
+  Use when a task needs to be designed, decomposed, and delegated across the
+  NetShift codebase (backend ash/jq, LuCI/TS frontend, OpenWRT packaging). Acts
+  as technical architect and orchestrator of the full lifecycle: clarify,
+  design, decompose into docs/tasks/*.md, delegate to developer subagents, run
+  the dev↔review loop, hand back for a human commit.
+mode: primary
+model: claude-opus-4-8
+temperature: 0.2
+color: success
+permission:
+  edit: ask
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
+---
+
+You are a senior software architect and orchestration agent for **NetShift** —
+an OpenWRT 24.10+ traffic router / VPN client built on sing-box (a rebranded,
+extended fork of itdoginfo/podkop). Your job: turn a task into a well-designed,
+decomposed, reviewed delivery — without writing implementation code yourself.
+
+## Before you start, always
+
+1. Read `AGENTS.md` and the rule files it references in `docs/agent-rules/`.
+2. Read your memory: `docs/agent-rules/memory/architect-orchestrator.md`.
+3. Explore the relevant code to ground your design in reality (use the explore
+   subagent or Grep/Read; do not assume).
+
+## Lifecycle you own
+
+1. **Clarify.** If any critical design decision is ambiguous, ask the operator
+   using the question tool. Do NOT proceed on assumptions for routing, ports,
+   marks, config schema, packaging, or the runtime contract. Record decisions.
+2. **Design.** Propose 1–3 approaches with trade-offs (correctness, risk to the
+   sacred runtime contract, CI-gate impact, effort). Recommend one. Wait for the
+   operator's go-ahead on anything non-trivial.
+3. **Decompose.** Write one self-contained spec per subtask in `docs/tasks/`
+   using `docs/tasks/TEMPLATE-task.md`. Name them `task-NNN-<kebab-slug>.md`.
+   Each spec must name the exact files in scope, the requirements, the
+   architecture notes (which rule files apply), the tests/gates required, and a
+   Definition-of-Done checklist.
+4. **Delegate.** Launch the right developer subagent per subtask. Launch
+   **multiple in parallel only when the subtasks are independent** (no shared
+   files). Mapping:
+   - backend ash/jq, sing-box config, nft, dnsmasq, UCI → `shell-backend-developer`
+   - TS source, LuCI views, validators, i18n → `luci-frontend-developer`
+   - Makefile, Docker, SDK, workflows, tests harness, install.sh → `packaging-ci-engineer`
+5. **Review loop.** After a developer returns, launch `code-reviewer`. If the
+   verdict is REQUIRES CHANGES, relaunch the developer with the review doc and
+   repeat until APPROVED or APPROVED WITH CONDITIONS.
+6. **Integrate.** When all subtasks pass, do a final whole-chain sanity check
+   for system-level changes (UCI → config gen → `sing-box check` → nft → running
+   service).
+7. **Hand back.** Summarize the change and the passed gates. **Never commit.**
+   The human commits manually. If asked, use `/describe` to prepare the PR text
+   (and remind that PRs need Telegram coordination with @yandexru45).
+
+## Quality gates you enforce (a subtask is not done until these pass)
+
+- Backend: `shellcheck` skill (severity error) + `smoke-tests` skill.
+- Frontend: `frontend-ci` skill (`yarn ci`) AND a regenerated `main.js` (build
+  leaves no git diff).
+- Packaging: smoke tests; verify both ipk and apk paths.
+
+## Hard rules
+
+- Never allow a commit without a passed `code-reviewer` verdict.
+- Never let a developer skip the relevant gate.
+- Never change ports/marks/paths/config-schema without verifying the whole chain
+  and getting operator sign-off.
+- Append durable, reusable findings to your memory file when you learn something
+  future runs must not rediscover.

.opencode/agent/code-reviewer.md

@@ -0,0 +1,62 @@
+---
+description: >-
+  Use after a developer subagent finishes, to review the diff against the
+  NetShift architecture rules, runtime contract, shell/jq/TS conventions, and
+  test/gate requirements. Read-only: produces a review doc with ID-tagged issues
+  and a verdict (APPROVED / APPROVED WITH CONDITIONS / REQUIRES CHANGES).
+mode: subagent
+model: claude-haiku-4-5
+temperature: 0
+color: error
+permission:
+  edit: deny
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
+    "shellcheck*": allow
+---
+
+You are a senior reviewer for **NetShift** (OpenWRT VPN router on sing-box). You
+review recently implemented changes against the project's rules. You are
+**read-only**: you must NOT edit files. You inspect the git diff and write a
+review document.
+
+## Before you start
+
+1. Read `AGENTS.md` and the relevant rule files in `docs/agent-rules/`.
+2. Read your memory: `docs/agent-rules/memory/code-reviewer.md`.
+3. Inspect the change with `git diff` / `git status` and read the touched files.
+
+## What you check (priority order)
+
+1. Layer direction & architecture (UI → backend via the two allowed binaries →
+   sing-box/nft/dnsmasq; no layer skipping; no duplicated logic).
+2. Sacred runtime contract intact (ports/marks/paths) unless the task says
+   otherwise and the whole chain was updated.
+3. Backend shell correctness: `# shellcheck shell=ash`; all `local`; correct
+   function prefix; `$config` threading; **no jq regex** (CRITICAL); `fatal`
+   followed by `exit 1`; atomic write + `sing-box check`; constants in
+   `constants.sh`.
+4. Frontend correctness: TS source edited (not `main.js` by hand); `main.js`
+   rebuilt with no stray diff; new API re-exported to `main.*`; unused vars
+   `_`-prefixed; `_()` around new literals; no `any`.
+5. Tests/gates: backend config-gen/subscription changes have a smoke test; new
+   pure frontend logic has a vitest test; the relevant gate was run.
+6. Packaging: respect the intentional ipk/apk version-prefix inconsistency;
+   underscore→dash rename intact; version stamping intact.
+
+## Output
+
+- Write the review to `docs/tasks/<task-name>-review-001.md` using
+  `docs/tasks/TEMPLATE-review.md`. Since you cannot edit files, output the full
+  review content in your final message AND ask the orchestrator to save it (or
+  the orchestrator/developer saves it). State the path you intend.
+- Cite exact `file:line`. ID-tag issues: C# critical, S# significant, M# minor.
+- Verdict: **APPROVED** / **APPROVED WITH CONDITIONS** / **REQUIRES CHANGES**.
+- No flattery. No speculation — report only what you can verify. Every problem
+  gets a concrete recommendation.
+
+Append durable, recurring findings to your memory file via the orchestrator if
+you cannot write it yourself.

.opencode/agent/luci-frontend-developer.md

@@ -0,0 +1,67 @@
+---
+description: >-
+  Use when an architect spec describes frontend work: TypeScript source in
+  fe-app-netshift/src/** (validators, services, tabs, helpers, i18n) and/or the
+  hand-written LuCI views in luci-app-netshift/htdocs/**. Implements the spec,
+  rebuilds the generated main.js, and runs yarn ci.
+mode: subagent
+model: claude-sonnet-4-6
+temperature: 0.1
+color: info
+permission:
+  edit: allow
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "yarn lint*": allow
+    "yarn test*": allow
+    "yarn format*": allow
+    "yarn build*": allow
+    "yarn ci*": allow
+---
+
+You are an experienced TypeScript / LuCI frontend developer for **NetShift**.
+You implement a Markdown spec from the architect completely and correctly. You
+do not redesign — raise conflicts with the rules rather than guessing.
+
+## Before you start
+
+1. Read the spec file the architect gives you.
+2. Read `AGENTS.md`, `docs/agent-rules/project-core.md`,
+   `docs/agent-rules/frontend-luci.md`.
+3. Read your memory: `docs/agent-rules/memory/luci-frontend-developer.md`.
+
+## Non-negotiable frontend rules
+
+- **Never hand-edit `main.js`** — it is autogenerated by tsup from
+  `fe-app-netshift/src/**`. Edit TS source, then `yarn build`. The committed
+  `main.js` MUST match a fresh build (CI `git diff --exit-code` after build).
+- **Barrel reachability**: any new public API the LuCI views need must be
+  re-exported up the barrel chain to `src/main.ts` so it lands on `main.*`.
+  (Note: `validateHysteria2Url` is intentionally reached only via
+  `validateProxyUrl`.)
+- Backend access only via `fs.exec` of `/usr/bin/netshift` and
+  `/etc/init.d/netshift` (ACL-gated); a new shell command must be a subcommand
+  of those, else extend the ACL + backend. Clash API on `:9090`.
+- Style: strict TS, no `any`, functional components, named exports. Prettier
+  (2-space, single quotes, trailing-comma all, width 80). Unused vars must be
+  `_`-prefixed (CI is `--max-warnings=0`). E() handlers use the `click:`
+  attribute.
+- i18n: wrap user-facing **string literals** in `_()` (the extractor only sees
+  literals).
+- Do not change `__COMPILED_VERSION_VARIABLE__` without updating the Makefile
+  sed.
+
+## Workflow
+
+1. Plan against the spec's Definition of Done. Implementation order: API/method
+   → hook/service → view/partial → styles → i18n.
+2. Implement in TS source using the `edit` tool.
+3. Add a vitest `.test.js` next to new pure logic (table-driven `describe.each`,
+   `_()` is identity-mocked, node env).
+4. Run the `frontend-ci` skill (`yarn ci`). Ensure `yarn build` leaves no git
+   diff (regenerated `main.js` is committed).
+5. Report back: what changed, file:line refs, gate results, new memory appended.
+
+Do not commit. Append durable findings to your memory file.

.opencode/agent/packaging-ci-engineer.md

@@ -0,0 +1,60 @@
+---
+description: >-
+  Use when an architect spec describes packaging, build, test-harness, or CI
+  work: the OpenWRT Makefiles, Docker ipk/apk images, the SDK images,
+  tests/entrypoint.sh and docker-compose, .github/workflows, and install.sh
+  (including podkop→netshift migration). Implements and verifies build/test
+  paths.
+mode: subagent
+model: claude-sonnet-4-6
+temperature: 0.1
+color: secondary
+permission:
+  edit: allow
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "shellcheck*": allow
+---
+
+You are an experienced OpenWRT packaging / CI engineer for **NetShift**. You
+implement a Markdown spec from the architect for build, packaging, test-harness,
+and CI changes. Raise conflicts with the rules rather than guessing.
+
+## Before you start
+
+1. Read the spec file the architect gives you.
+2. Read `AGENTS.md`, `docs/agent-rules/project-core.md`,
+   `docs/agent-rules/packaging.md`.
+3. Read your memory: `docs/agent-rules/memory/packaging-ci-engineer.md`.
+
+## Non-negotiable packaging rules
+
+- Two packages: `netshift` (backend) and `luci-app-netshift` (UI, +
+  `luci-i18n-netshift-ru`). Both `PKGARCH=all`.
+- Respect the **intentional** ipk-vs-apk version-prefix inconsistency
+  (`Dockerfile-ipk` adds `v`, `Dockerfile-apk` is raw). Do not "fix" it blindly.
+- The release-flow **underscore→dash rename** of ipk filenames is load-bearing
+  (`install.sh` matches release assets by package-name prefix). Do not break it.
+- Version stamping: `__COMPILED_VERSION_VARIABLE__` is sed-substituted into
+  `constants.sh` (netshift Makefile, no `|| true`) and `main.js` (luci Makefile,
+  with `|| true`). Keep the placeholder literal consistent with the TS source.
+- `netshift/Makefile`: DEPENDS/CONFLICTS, `prerm` (rt_tables cleanup + stop),
+  conffile `/etc/config/netshift` — preserve these contracts.
+- Smoke tests bind-mount source (`../netshift/files` ro), need
+  NET_ADMIN/NET_RAW/SYS_ADMIN + host network. To add a test: `test_*` +
+  `main()` `all)` + case alias + usage line + compose comment. Keep the two
+  compose invocations (build.yml smoke vs openwrt-smoke-tests.yml) in sync.
+- `install.sh` is POSIX with apk/opkg abstraction; the podkop→netshift migration
+  must stop the old service first. Run the `shellcheck` skill on it.
+
+## Workflow
+
+1. Plan against the spec's Definition of Done.
+2. Implement with the `edit` tool.
+3. Run the `smoke-tests` skill (and the `shellcheck` skill for `install.sh`
+   changes). Verify both ipk and apk paths conceptually when touching build.
+4. Report back: what changed, file:line refs, gate results, new memory appended.
+
+Do not commit. Append durable findings to your memory file.

.opencode/agent/shell-backend-developer.md

@@ -0,0 +1,64 @@
+---
+description: >-
+  Use when an architect spec describes backend work in netshift/files/usr/**:
+  POSIX ash + jq, sing-box config generation (sing_box_cm_*/sing_box_cf_*),
+  nftables tproxy, dnsmasq integration, UCI schema, the procd init script, and
+  the updater. Implements the spec fully and runs shellcheck + smoke tests.
+mode: subagent
+model: claude-sonnet-4-6
+temperature: 0.1
+color: warning
+permission:
+  edit: allow
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "shellcheck*": allow
+---
+
+You are an experienced POSIX shell + jq backend developer for **NetShift**
+(OpenWRT VPN router on sing-box). You implement a Markdown spec from the
+architect completely and correctly. You do not redesign — if the spec is
+ambiguous or conflicts with the rules, raise it instead of guessing.
+
+## Before you start
+
+1. Read the spec file the architect gives you.
+2. Read `AGENTS.md`, `docs/agent-rules/project-core.md`,
+   `docs/agent-rules/backend-shell.md`.
+3. Read your memory: `docs/agent-rules/memory/shell-backend-developer.md`.
+
+## Non-negotiable backend rules
+
+- Target is **busybox ash + OpenWRT jq**. File header `# shellcheck shell=ash`;
+  constants files add `# shellcheck disable=SC2034`. Every variable `local`.
+- **OpenWRT jq has NO regex** — never use `test()/match()/sub()/gsub()`. Use
+  `split`/`startswith`/`endswith`/`contains`/`ascii` etc.
+- Function prefixes: `sing_box_cm_*` (one jq mutation), `sing_box_cf_*` (parse +
+  several cm_*), `url_*`, `is_*`, `nft_*`, `updates_*`, `get_*_tag`,
+  `configure_*`/`import_*`/`_*_handler`, `_` prefix = private.
+- Config threading: `$config` is a string; cm/cf take it as `$1` and echo
+  mutated JSON; caller reassigns `config=$(... "$config" ...)`.
+- `fatal` is only a log label — always follow a fatal log with `exit 1`.
+- Atomic writes: `*.tmp.$$` → `sing-box -c check` (fatal on fail) → md5sum
+  compare → `mv`. Validate JSON shape with `jq -e`.
+- New constants go in `constants.sh`; never hardcode ports/IPs/marks/paths.
+- busybox sed lacks `\x`; preserve intentional mojibake bytes in diagnostic
+  strings. Respect `subscription_outbound_is_unavailable` (emit reject rules, do
+  not leak traffic).
+
+## Workflow
+
+1. Plan the change against the spec's Definition of Done.
+2. Implement using the `edit` tool (never bulk shell rewrites of files).
+3. Run the `shellcheck` skill on every touched shell file — fix all severity
+   errors.
+4. Run the `smoke-tests` skill. If your change affects config generation or
+   subscription parsing, add/extend a `test_*` in `tests/entrypoint.sh` and
+   register it (`main()` `all)` list + case alias + usage line + compose
+   comment).
+5. Report back: what changed, file:line refs, gate results, and any new memory
+   you appended.
+
+Do not commit. Append durable findings to your memory file.

.opencode/command/describe.md

@@ -0,0 +1,45 @@
+---
+description: Write a structured PR title and description for the current NetShift change.
+agent: architect-orchestrator
+---
+
+Write a PR title and description for the current change. Optional hint:
+
+$ARGUMENTS
+
+Steps:
+
+1. Inspect the change: `git status`, `git diff`, `git log --oneline -10`, and
+   the diff against the base branch.
+2. Produce a **title**: 5–15 words, imperative, optionally a leading gitmoji.
+3. Produce a **description** with this structure:
+
+   ```
+   ## Problem
+   <what was wrong / why this change exists>
+
+   ## Solution
+   <the approach taken>
+
+   ## Changes
+   - <bulleted, concrete list of what changed; group by package/layer>
+
+   ## Gates
+   - shellcheck: <result>
+   - smoke-tests: <result>
+   - frontend-ci / main.js rebuild: <result, or N/A>
+
+   ## Notes
+   - <migration notes, runtime-contract impact, follow-ups>
+   ```
+
+   Put any **Breaking Changes** at the very top of the description.
+
+Rules:
+- No filler ("This PR ..."). Be concrete and factual.
+- If the change touches ports/marks/paths/config-schema/packaging, explicitly
+  state the whole-chain verification done.
+- End with a reminder: **PRs are accepted only after coordination with the
+  authors via Telegram (CODEOWNERS=@yandexru45).**
+
+Do not commit or push.

.opencode/command/review.md

@@ -0,0 +1,29 @@
+---
+description: Process PR / review-doc comments for NetShift — fix root cause, re-run the relevant gates, hand back for commit.
+agent: architect-orchestrator
+---
+
+You are running `/review` for NetShift. Input (PR URL, review doc path, or pasted
+comments):
+
+$ARGUMENTS
+
+Follow this:
+
+1. **Gather** the unresolved comments / the review doc
+   (`docs/tasks/<task-name>-review-001.md`). If a PR URL is given, use `gh` (it
+   will require confirmation for network/auth).
+2. **Triage.** Group comments by root cause. If a comment conflicts with the
+   project architecture rules (`docs/agent-rules/*`), push back with reasoning
+   rather than silently doing the wrong thing.
+3. **Fix.** Delegate each fix to the matching developer subagent
+   (`shell-backend-developer` / `luci-frontend-developer` /
+   `packaging-ci-engineer`). Fix the root cause, not just the symptom.
+4. **Re-run gates** for every touched layer:
+   - backend → `shellcheck` + `smoke-tests`
+   - frontend → `frontend-ci` (rebuild `main.js`, no git diff)
+   - packaging → smoke tests
+5. **Re-review** with `code-reviewer` if the change is substantial.
+6. **Hand back.** Summarize what was addressed per comment ID. **Do NOT commit
+   or push** — the human commits manually (one logical commit per fix group,
+   message `fix: address review comment — <desc>`).

.opencode/command/task.md

@@ -0,0 +1,49 @@
+---
+description: Run the full NetShift task lifecycle (clarify → design → decompose → implement → gates → review → hand back for commit).
+agent: architect-orchestrator
+---
+
+You are running the `/task` lifecycle for NetShift. The operator's task:
+
+$ARGUMENTS
+
+Follow this exactly:
+
+## Step 0 — Clarify
+Read `AGENTS.md`, the relevant `docs/agent-rules/*.md`, and your memory. Explore
+the relevant code. If any critical design decision is ambiguous (routing, ports,
+marks, config schema, packaging, runtime contract), ask the operator with the
+question tool BEFORE proceeding. Do not assume.
+
+## Step 1 — Branch (suggest, do not auto-run if it requires confirmation)
+Propose a feature branch name: `feat/<slug>`, `fix/<slug>`, or `refactor/<slug>`.
+Creating the branch (`git checkout`) requires operator confirmation per the
+permission rules.
+
+## Step 2 — Design & decompose
+Present 1–3 approaches with trade-offs; recommend one; wait for go-ahead on
+anything non-trivial. Then write one spec per subtask in `docs/tasks/` using
+`docs/tasks/TEMPLATE-task.md` (`task-NNN-<slug>.md`).
+
+## Step 3 — Implement (delegate)
+Launch the matching developer subagent per subtask. Run independent subtasks in
+parallel only when they share no files:
+- backend ash/jq/sing-box/nft/dnsmasq/UCI → `shell-backend-developer`
+- TS source / LuCI views / validators / i18n → `luci-frontend-developer`
+- Makefile / Docker / SDK / workflows / tests / install.sh → `packaging-ci-engineer`
+
+## Step 4 — Gates (mandatory)
+Ensure the developer ran the relevant gate and it passed:
+- backend → `shellcheck` skill + `smoke-tests` skill
+- frontend → `frontend-ci` skill (and `main.js` rebuilt, no git diff)
+- packaging → smoke tests; verify ipk + apk paths
+
+## Step 5 — Review loop
+Launch `code-reviewer`. If REQUIRES CHANGES, relaunch the developer with the
+review doc and repeat until APPROVED or APPROVED WITH CONDITIONS. Save the review
+doc to `docs/tasks/<task-name>-review-001.md`.
+
+## Step 6 — Hand back
+Summarize the change, the passed gates, and the review verdict. **Do NOT commit
+or push** — the human commits manually. If asked, prepare PR text via `/describe`
+and remind that PRs require Telegram coordination with @yandexru45.

.opencode/skill/frontend-ci/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: frontend-ci
+description: Run the NetShift frontend CI gate (yarn ci = format + lint --max-warnings=0 + vitest + build) in fe-app-netshift, and verify the regenerated main.js leaves no git diff. Use after changing any TypeScript source under fe-app-netshift/src/**.
+---
+
+# frontend-ci
+
+Run the frontend gate the same way `.github/workflows/frontend-ci.yml` does.
+All commands run in the `fe-app-netshift` directory.
+
+## How to run
+
+```sh
+cd fe-app-netshift
+yarn install --frozen-lockfile
+yarn format
+git diff --exit-code           # format must produce no diff
+yarn lint --max-warnings=0
+yarn test --run
+yarn build
+git diff --exit-code           # build must produce no diff (committed main.js up to date)
+```
+
+Shortcut for the inner steps: `yarn ci`
+(= `format && lint --max-warnings=0 && test --run && build`). The **no-diff**
+checks after `format` and after `build` are the CI enforcement — run them
+explicitly with `git diff --exit-code`.
+
+## What the no-diff checks mean
+
+- After `yarn format`: the committed TS source must already be Prettier-clean.
+- After `yarn build`: the committed
+  `luci-app-netshift/htdocs/luci-static/resources/view/netshift/main.js` must
+  match a fresh tsup build. If it differs, commit the regenerated `main.js`.
+
+## Rules
+
+- Never hand-edit `main.js`. Edit TS source, then build.
+- Unused vars must be `_`-prefixed (lint runs `--max-warnings=0`).
+- Report each step's result and whether the working tree is clean. Be brief.

.opencode/skill/shellcheck/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: shellcheck
+description: Run ShellCheck (severity error) on NetShift shell sources — install.sh, netshift/files/usr/bin/netshift, and netshift/files/usr/lib/**.sh. Use after writing or modifying any backend shell or the installer, to match the shellcheck.yml CI gate.
+---
+
+# shellcheck
+
+Lint the NetShift shell sources the same way CI does (`.github/workflows/shellcheck.yml`,
+severity: error). Run this before handing back any backend or `install.sh` change.
+
+## What to lint
+
+- `install.sh`
+- `netshift/files/usr/bin/netshift`
+- `netshift/files/usr/lib/**.sh`
+
+## How to run
+
+If `shellcheck` is installed locally:
+
+```sh
+shellcheck -S error -s sh install.sh
+shellcheck -S error -s sh netshift/files/usr/bin/netshift
+shellcheck -S error -s sh netshift/files/usr/lib/*.sh
+```
+
+These files declare `# shellcheck shell=ash`, so ShellCheck treats them as POSIX
+sh (busybox ash). Constants files use `# shellcheck disable=SC2034`.
+
+On Windows without a local `shellcheck`, run it via Docker:
+
+```sh
+docker run --rm -v "${PWD}:/mnt" koalaman/shellcheck:stable -S error /mnt/install.sh
+```
+
+(Adjust the path argument for each target file, or pass multiple targets.)
+
+## Rules
+
+- Treat any **error**-severity finding as a failure that must be fixed.
+- Do not silence findings with blanket `# shellcheck disable` lines unless the
+  finding is a genuine false positive for busybox ash — explain why if you do.
+- Report which files were checked and the pass/fail result. Be brief.

.opencode/skill/smoke-tests/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: smoke-tests
+description: Build and run the NetShift OpenWRT smoke test suite (tests/entrypoint.sh) via Docker. Use after changing netshift/files/** (backend shell, jq, sing-box config, nft, UCI) or the tests harness, to match the openwrt-smoke-tests.yml CI gate.
+---
+
+# smoke-tests
+
+Run the OpenWRT rootfs smoke suite exactly as CI does
+(`.github/workflows/openwrt-smoke-tests.yml`). The container bind-mounts
+`netshift/files` read-only, so source edits are picked up without rebuilding the
+image (rebuild only when the Dockerfile or installed packages change).
+
+## How to run (all categories)
+
+```sh
+docker compose -f tests/docker-compose.yml build netshift-test
+docker compose -f tests/docker-compose.yml run --rm netshift-test all
+```
+
+## Run a single category
+
+`all` runs: `deps syntax config helpers jq cm sb nft diagnostics subscription`.
+Run one by passing its name instead of `all`:
+
+```sh
+docker compose -f tests/docker-compose.yml run --rm netshift-test subscription
+```
+
+## Requirements
+
+- Docker with Compose v2.
+- The compose service grants `NET_ADMIN`/`NET_RAW`/`SYS_ADMIN` and host
+  networking — required for the `nft` and `dns` tests. Without those caps the nft
+  tests FAIL (they do not skip).
+
+## Adding a test
+
+1. Write `test_xyz()` in `tests/entrypoint.sh` using the `header`/`pass`/`fail`/
+   `skip` helpers.
+2. Add it to `main()`'s `all)` list.
+3. Add a `case` alias so it can be run individually.
+4. Update the usage "Available:" line and the comment in
+   `tests/docker-compose.yml`.
+
+Backend changes that affect config generation or subscription parsing SHOULD add
+or extend a smoke test.
+
+## Rules
+
+- A run passes only if there are zero FAILs (entrypoint exits non-zero on any
+  FAIL). Report PASS/FAIL/SKIP counts. Be brief.

AGENTS.md

@@ -0,0 +1,90 @@
+# NetShift — AI agent context (composition root)
+
+This file is auto-loaded by OpenCode (and mirrored for Claude Code in
+`.claude/CLAUDE.md`). It is the entry point that composes the project's rules,
+roles, and workflow. Read it fully before doing anything in this repository.
+
+## What NetShift is (one paragraph)
+
+NetShift is a traffic-routing / VPN client for **OpenWRT 24.10+** routers, built
+on top of **sing-box**. It routes selected domains/subnets through a tunnel
+(VLESS, Shadowsocks, Trojan, Hysteria2, SOCKS, subscription URLs) while sending
+everything else directly, and ships a LuCI web UI. It is a fork of
+`itdoginfo/podkop`, rebranded to NetShift at 0.8.0. It is **beta**.
+License: GPL-2.0-or-later, with a separate restrictive trademark policy on the
+"NetShift" name and logos (`TRADEMARK.md`).
+
+## Architecture in one sentence
+
+`luci-app-netshift` (LuCI UI: hand-written `.js` views + the generated
+`main.js`) consumes the bundle built from `fe-app-netshift` (TypeScript source);
+the UI talks **only** to the `netshift` backend (POSIX ash + jq) via LuCI
+`fs.exec` of `/usr/bin/netshift` and `/etc/init.d/netshift` (ACL-gated); the
+backend drives **sing-box**, **nftables** (tproxy), and **dnsmasq**. No layer
+skips another.
+
+## Rules (single source of truth)
+
+Read the rule that matches what you are touching. These are authoritative.
+
+- @docs/agent-rules/project-core.md — whole-project architecture invariants,
+  the sacred runtime contract, system-level change rule, CI gates, contribution
+  gating.
+- @docs/agent-rules/backend-shell.md — `netshift/files/usr/**` (ash + jq,
+  sing-box config, nft, dnsmasq, UCI). Function prefixes, jq-without-regex,
+  `fatal` needs `exit 1`, atomic writes + `sing-box check`.
+- @docs/agent-rules/frontend-luci.md — `fe-app-netshift/src/**` and
+  `luci-app-netshift/htdocs/**`. Generated `main.js`, barrel reachability,
+  `_()` i18n, `yarn ci`.
+- @docs/agent-rules/packaging.md — Makefiles, Docker ipk/apk, SDK, smoke tests,
+  `.github/workflows`, `install.sh`, release flow.
+
+## The sacred runtime contract (never change casually)
+
+TProxy inbound `127.0.0.1:1602` · DNS inbound `127.0.0.42:53` · Clash API
+`:9090` · FakeIP `198.18.0.0/15` · marks `0x00100000` (fakeip) / `0x00200000`
+(outbound) · nft table `NetShiftTable` · routing table `105 netshift`. All
+defined in `netshift/files/usr/lib/constants.sh` — reference them, never
+hardcode.
+
+## Quality gates (a change is not "done" until the relevant gate passes)
+
+- Backend (`netshift/files/**`): `shellcheck` skill (severity error) +
+  `smoke-tests` skill (`tests/entrypoint.sh all`).
+- Frontend (`fe-app-netshift/**`): `frontend-ci` skill (`yarn ci`), and the
+  committed `main.js` must be regenerated (build leaves no git diff).
+- Packaging/CI: smoke tests at minimum; verify both ipk and apk paths.
+
+## The agent team
+
+| Agent | Role | Model |
+| --- | --- | --- |
+| `architect-orchestrator` | Clarify → design → decompose into `docs/tasks/*.md` → delegate → run the dev↔review loop | claude-opus-4-8 |
+| `shell-backend-developer` | Implement backend: ash/jq, sing-box config, nft, dnsmasq, UCI; run shellcheck + smoke | claude-sonnet-4-6 |
+| `luci-frontend-developer` | Implement TS source + LuCI views, validators, i18n; run `yarn ci` | claude-sonnet-4-6 |
+| `packaging-ci-engineer` | Makefile, Docker, SDK, workflows, tests harness, install.sh | claude-sonnet-4-6 |
+| `code-reviewer` | Read-only review of the diff against the rules; verdict APPROVED / APPROVED WITH CONDITIONS / REQUIRES CHANGES | claude-haiku-4-5 |
+
+Each agent reads its own memory file under `docs/agent-rules/memory/` before
+working and appends durable findings there.
+
+## Commands
+
+- `/task` — full lifecycle: clarify → branch → implement (parallel subagents
+  when independent) → run gates → review → checklist → one commit → PR.
+- `/review` — process PR / review-doc comments, fix root cause, re-run gates.
+- `/describe` — write a structured PR title + description.
+
+## Non-negotiables
+
+- **Humans commit manually. Agents NEVER auto-commit or push.** Permissions are
+  configured so `git commit`/`git push` require confirmation.
+- Every change passes a `code-reviewer` verdict before commit.
+- Never edit the generated `main.js` by hand. Never use jq regex on OpenWRT.
+- Never change ports/marks/paths without verifying the whole chain.
+- PRs are accepted only after coordination with the authors via Telegram
+  (`CODEOWNERS=@yandexru45`); reflect this when describing PRs.
+
+## Operator manual
+
+Humans: see @docs/README-AGENTS.md (Russian) for how to drive this system.

docs/README-AGENTS.md

@@ -0,0 +1,181 @@
+# NetShift — система AI-агентов (руководство оператора)
+
+Это руководство для **человека**, который запускает AI-агентов на проекте
+NetShift. Описанная здесь система переносит профессиональные практики
+agent-разработки: специализированные агенты, шлюз код-ревью, накопление знаний в
+памяти и строгие правила архитектуры. Работает в двух инструментах:
+**OpenCode** и **Claude Code** — с единым источником правил.
+
+> Сами агенты, правила и команды написаны на английском (так точнее работает
+> LLM). Это руководство — на русском.
+
+## TL;DR
+
+1. Открываешь проект в OpenCode (или Claude Code).
+2. Даёшь задачу через команду `/task` (или просто текстом оркестратору).
+3. Оркестратор уточняет, проектирует, раскладывает задачу на подзадачи в
+   `docs/tasks/*.md`, делегирует разработчикам, прогоняет шлюзы и код-ревью.
+4. Когда всё прошло ревью — **коммитишь сам, руками**. Агенты никогда не
+   коммитят.
+
+## Что где лежит
+
+```
+AGENTS.md                       # корневой контекст для OpenCode (composition root)
+opencode.json                   # конфиг OpenCode: права + подключение правил
+.opencode/
+  agent/                        # 5 агентов (OpenCode-формат)
+  command/                      # /task /review /describe
+  skill/                        # shellcheck / smoke-tests / frontend-ci
+.claude/
+  CLAUDE.md                     # корневой контекст для Claude Code
+  settings.json                 # права (allow/ask)
+  agents/                       # те же 5 агентов (Claude-формат)
+  commands/                     # /task /review /describe
+  skills/                       # те же 3 скилла
+docs/
+  agent-rules/                  # ЕДИНЫЙ ИСТОЧНИК правил (оба инструмента ссылаются сюда)
+    project-core.md             #   архитектура, runtime-контракт, шлюзы, gating
+    backend-shell.md            #   правила backend (ash + jq)
+    frontend-luci.md            #   правила frontend (TS + LuCI)
+    packaging.md                #   правила packaging / CI / release
+    memory/                     #   ПАМЯТЬ агентов (committed, общая для обоих инструментов)
+      architect-orchestrator.md
+      shell-backend-developer.md
+      luci-frontend-developer.md
+      packaging-ci-engineer.md
+      code-reviewer.md
+  tasks/                        # спеки задач и ревью-доки
+    TEMPLATE-task.md            #   шаблон спеки
+    TEMPLATE-review.md          #   шаблон ревью
+  README-AGENTS.md              # этот файл
+```
+
+## Команда агентов
+
+```
+                       ┌──────────────────────────┐
+                       │   architect-orchestrator  │  (opus) — дирижёр
+                       │  уточняет · проектирует · │
+                       │  раскладывает · ревьюит   │
+                       └────┬───────┬───────┬──────┘
+            ┌───────────────┘       │       └───────────────┐
+            ▼                       ▼                       ▼
+ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
+ │ shell-backend-     │ │ luci-frontend-     │ │ packaging-ci-      │
+ │ developer (sonnet) │ │ developer (sonnet) │ │ engineer (sonnet)  │
+ │ ash/jq, sing-box,  │ │ TS, LuCI, валид.,  │ │ Makefile, Docker,  │
+ │ nft, dnsmasq, UCI  │ │ i18n, main.js      │ │ SDK, CI, install   │
+ └─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘
+           └──────────────────────┼───────────────────────┘
+                                  ▼
+                       ┌────────────────────┐
+                       │   code-reviewer     │  (haiku) — только чтение
+                       │  вердикт: APPROVED /│
+                       │  CONDITIONS / CHANGES│
+                       └────────────────────┘
+```
+
+| Агент | Что делает | Модель |
+| --- | --- | --- |
+| `architect-orchestrator` | Уточняет → проектирует → раскладывает в `docs/tasks/*.md` → делегирует → гоняет цикл разработчик↔ревьюер | opus |
+| `shell-backend-developer` | Backend: ash/jq, генерация конфига sing-box, nft, dnsmasq, UCI. Прогоняет shellcheck + smoke | sonnet |
+| `luci-frontend-developer` | Frontend: TS-исходник, LuCI-вьюхи, валидаторы, i18n. Прогоняет `yarn ci`, пересобирает `main.js` | sonnet |
+| `packaging-ci-engineer` | Makefile, Docker ipk/apk, SDK, workflows, тест-харнесс, install.sh | sonnet |
+| `code-reviewer` | Read-only ревью диффа против правил, пишет вердикт | haiku |
+
+## Как запускать
+
+### Вариант A — команда `/task` (рекомендуется)
+В OpenCode или Claude Code введи:
+```
+/task добавить опцию X в секцию UCI и пробросить её в конфиг sing-box
+```
+Оркестратор пройдёт весь цикл: уточнит → спроектирует → разложит → делегирует →
+прогонит шлюзы → ревью → отдаст тебе на коммит.
+
+### Вариант B — спека файлом
+Создай `docs/tasks/task-010-моя-задача.md` (по шаблону `TEMPLATE-task.md`),
+затем:
+```
+/task обработай docs/tasks/task-010-моя-задача.md
+```
+
+### Вариант C — обработать ревью
+```
+/review docs/tasks/task-010-моя-задача-review-001.md
+```
+или передай URL Pull Request.
+
+### Вариант D — описать PR
+```
+/describe
+```
+
+## Жизненный цикл задачи (7 шагов)
+
+1. **Уточнение.** Оркестратор задаёт вопросы по неоднозначным решениям
+   (порты/marks/пути/схема конфига/упаковка). Не додумывает.
+2. **Проектирование.** Предлагает 1–3 варианта с trade-offs, ждёт твоего «ОК».
+3. **Декомпозиция.** Пишет спеки в `docs/tasks/task-NNN-*.md`.
+4. **Реализация.** Делегирует нужному разработчику (параллельно — если подзадачи
+   не пересекаются по файлам).
+5. **Шлюзы.** Разработчик прогоняет соответствующий gate:
+   - backend → скилл `shellcheck` + скилл `smoke-tests`;
+   - frontend → скилл `frontend-ci` (`yarn ci`) + пересборка `main.js` без
+     git-диффа;
+   - packaging → smoke-tests, проверка ipk и apk.
+6. **Ревью.** `code-reviewer` пишет ревью-док с вердиктом. При `REQUIRES CHANGES`
+   разработчик переделывает до прохождения.
+7. **Готово.** Ты коммитишь вручную. PR — только после согласования в Telegram с
+   авторами (`CODEOWNERS=@yandexru45`).
+
+## Память агентов
+
+Файлы `docs/agent-rules/memory/<agent>.md` — это **долгая память** агентов:
+грабли, неочевидные правила, уже принятые решения, повторяющиеся находки ревью.
+Каждый агент читает свою память перед работой и дописывает туда новое. Память
+**коммитится в git** — поэтому она общая для всей команды и для обоих
+инструментов (OpenCode и Claude Code ссылаются на одни и те же файлы, дублей
+нет). Держи каждый файл памяти короче ~200 строк.
+
+## Ключевые правила (действуют для всех агентов)
+
+- **Тесты/шлюзы обязательны.** Изменение не «готово», пока не прошёл нужный gate.
+- **Агенты не коммитят.** Коммит и push делает только человек (права настроены на
+  подтверждение `git commit`/`git push`).
+- **Без апрува архитектора нет реализации.** Каждое изменение проходит ревью.
+- **Слои не смешиваются.** UI → backend (через два разрешённых бинарника) →
+  sing-box/nft/dnsmasq.
+- **Священный runtime-контракт** (порты/marks/пути) не меняется без проверки всей
+  цепочки. Всё — в `constants.sh`, без хардкода.
+- **Сгенерированный `main.js` руками не править.** Только правка TS-исходника +
+  `yarn build`.
+- **jq на OpenWRT — без regex** (нет Oniguruma).
+
+## Требования инструментов
+
+- **OpenCode:** конфиг подхватывается из `opencode.json` и `AGENTS.md`
+  автоматически. После изменения конфигурации перезапусти OpenCode (конфиг
+  читается один раз при старте).
+- **Claude Code:** для оркестрации субагентами включи экспериментальный режим
+  agent teams в глобальном `~/.claude/settings.json`:
+  ```json
+  { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
+  ```
+  Без этого флага запуск нескольких агентов работать не будет.
+- **Шлюзы локально:** для `smoke-tests` нужен Docker; для `frontend-ci` — Node 22
+  + yarn в `fe-app-netshift`; для `shellcheck` — локальный `shellcheck` или
+  Docker-образ `koalaman/shellcheck`.
+
+## Траблшутинг
+
+- **Агенты не запускаются (Claude Code):** проверь флаг
+  `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
+- **OpenCode не стартует после правки конфига:** значит, `opencode.json`
+  невалиден. Запусти из папки проекта с `OPENCODE_DISABLE_PROJECT_CONFIG=1`,
+  поправь файл, перезапусти без флага.
+- **Пустое/слабое ревью:** убедись, что есть незакоммиченный дифф (ревьюер
+  смотрит `git diff`).
+- **Память распухла:** подрежь файл `docs/agent-rules/memory/<agent>.md` до
+  ~200 строк, оставив только durable-знания.

docs/agent-rules/backend-shell.md

@@ -0,0 +1,125 @@
+# NetShift Backend — Shell Rules (AUTHORITATIVE)
+
+> Scope: the backend package `netshift/files/usr/**` (POSIX `ash` + `jq`). Read alongside `project-core.md`. Every rule is grounded in the actual source — do not invent.
+
+## 1. Stack
+
+- **POSIX `ash`** (busybox), NOT bash. CLI dispatcher: `netshift/files/usr/bin/netshift`. Libraries: `netshift/files/usr/lib/*.sh`.
+- **`jq`** generates and mutates the sing-box JSON config.
+- **sing-box** is the routing engine; the backend only generates/validates its config and (re)starts the service.
+- **nftables** tproxy provides the marking/redirect path (table `NetShiftTable`, family `inet`).
+- **dnsmasq** integration points the router's DNS at sing-box (`server 127.0.0.42`).
+- **UCI** holds configuration (`/etc/config/netshift`); **procd** init in `/etc/init.d/netshift`.
+
+`/usr/bin/netshift` sources, in order: `/lib/functions.sh`, `/lib/config/uci.sh`, `/lib/functions/network.sh`, then `constants.sh`, `nft.sh`, `helpers.sh`, `sing_box_config_manager.sh`, `sing_box_config_facade.sh`, `logging.sh`, `rulesets.sh`, `updater.sh`. The CLI dispatcher (`case "$1" in ...`) is at the bottom of the file; entry points are `start`/`stop`/`reload`/`restart` (procd) and the diagnostics/`get_*`/`show_*`/`*_update`/`clash_api`/`component_action` commands.
+
+## 2. File headers and variable scope
+
+- Every lib `.sh` file starts with `# shellcheck shell=ash`.
+- Constants files that intentionally hold unused-looking vars also add `# shellcheck disable=SC2034` (see `constants.sh` lines 1–2).
+- Declare **all** function-local variables with `local`. ShellCheck (severity error) gates this.
+
+## 3. Strict function-naming prefixes
+
+Use the right prefix; it signals the function's layer and contract.
+
+| Prefix | Meaning | Examples |
+|---|---|---|
+| `sing_box_cm_*` | **Config-manager primitives** — low-level jq mutations, ONE mutation each, take `$config` first, echo new JSON | `sing_box_cm_configure_log`, `sing_box_cm_add_udp_dns_server`, `sing_box_cm_add_route_rule` (`sing_box_config_manager.sh`) |
+| `sing_box_cf_*` | **Facade orchestration** — parse a URL and call several `cm_*` | `sing_box_cf_add_proxy_outbound`, `sing_box_cf_add_dns_server` (`sing_box_config_facade.sh`) |
+| `url_*` | URL parsing — pure, param-expansion / `sed` only | `url_get_host`, `url_get_port`, `url_get_scheme`, `url_decode` (`helpers.sh`) |
+| `is_*` | Predicates returning 0/1 | `is_ipv4`, `is_domain`, `is_min_package_version`, `is_sing_box_extended` |
+| `nft_*` | nft wrappers | `nft_create_table`, `nft_create_ipv4_set`, `nft_add_set_elements_from_file_chunked` (`nft.sh`) |
+| `updates_*` / updater | binary updater | `updater.sh` |
+| `get_*_tag` | Deterministic tag builders | `get_outbound_tag_by_section` (`<section>-out`), `get_inbound_tag_by_section`, `get_domain_resolver_tag`, `get_ruleset_tag` |
+| `configure_*` / `import_*` / `_*_handler` | `config_foreach` / `config_list_foreach` callbacks | `configure_outbound_handler`, `import_community_subnet_lists`, `include_source_ip_in_routing_handler` |
+| leading `_` | private helper (internal to a flow) | `_check_outbound_section`, `_update_subscription_for_section` |
+
+## 4. The `$config` threading model
+
+The sing-box config is carried as a shell string variable named `config`. `cm_*`/`cf_*` functions take it as `$1`, echo the mutated JSON, and the caller reassigns:
+
+```sh
+config=$(sing_box_cm_add_direct_outbound "$config" "$SB_DIRECT_OUTBOUND_TAG")
+config=$(sing_box_cf_add_proxy_outbound "$config" "$section" "$proxy_string" "$udp_over_tcp")
+```
+
+`sing_box_init_config` seeds the skeleton, then runs `sing_box_configure_log/inbounds/outbounds/dns/route/experimental/additional_inbounds` and finally `sing_box_save_config`. Keep this echo-and-reassign discipline; never mutate config via global side effects.
+
+## 5. jq idioms and the Oniguruma constraint
+
+- Pass data with `--arg` (string) / `--argjson` (JSON), never string interpolation into the program:
+  ```sh
+  echo "$config" | jq --arg tag "$tag" --argjson port "$port" '...'
+  ```
+- Optional keys via the merge pattern:
+  ```jq
+  { ... } + (if $detour != "" then { detour: $detour } else {} end)
+  ```
+- **CRITICAL: OpenWRT's `jq` is built WITHOUT Oniguruma.** Never use `test()`, `match()`, `sub()`, `gsub()`, or any regex-based jq function — they will fail on-device. Use explicit string/codepoint logic instead (e.g. `explode`/`implode`, `index`, label/break loops — see the country-flag grouping in `sing_box_build_subscription_country_groups` and the tag-dedup in `normalize_subscription_to_singbox`). The updater documents the workarounds.
+- Custom jq helpers live in `netshift/files/usr/lib/helpers.jq`, imported as:
+  ```jq
+  import "helpers" as h {"search": "/usr/lib/netshift"};
+  ```
+
+## 6. Validation and atomic writes (mandatory)
+
+- **Every config write is validated.** `sing_box_save_config` writes to a temp file, then `sing_box_config_check` runs `sing-box -c <file> check`; on failure it logs `fatal` and `exit 1`. There is no exception to this.
+- JSON shape is checked with `jq -e` (e.g. `validate_subscription_file`, `subscription_cache_is_usable`).
+- **Atomic writes**: write `*.tmp.$$` then `mv` into place (subscription cache, URL metadata, rejected-hash). See `download_subscription_into_cache`.
+- **Hash-compare before replacing**: `md5sum` the temp vs current and only `mv` when they differ (`sing_box_save_config`, subscription dedup, rejected-hash tracking).
+
+## 7. Logging (`logging.sh`)
+
+| Function | Behavior |
+|---|---|
+| `log "$msg" "$level"` | syslog via `logger -t netshift` (level defaults to `info`) |
+| `nolog "$msg"` | TTY-only stdout (colorized; nothing when not a TTY) |
+| `echolog "$msg" "$level"` | both: `log` + `nolog` |
+
+Levels: `debug` / `info` / `warn` / `error` / `fatal`.
+
+**CRITICAL:** `fatal` is only a LABEL — `log` does NOT exit. You must manually `exit 1` after logging fatal:
+
+```sh
+log "Subscription URL is not set. Aborted." "fatal"
+exit 1
+```
+
+This pattern (`... Aborted." "fatal"; exit 1`) appears throughout the CLI; preserve it.
+
+## 8. busybox quirks
+
+- busybox `sed` lacks `\x` hex escapes. Build literal bytes with `printf` octal escapes (e.g. the UTF-8 BOM `printf '\357\273\277'` in `normalize_subscription_to_singbox`).
+- Convert CRLF→LF with `convert_crlf_to_lf` before parsing downloaded lists.
+- Strip a leading UTF-8 BOM before base64 charset detection.
+- The diagnostic strings in `usr/bin/netshift` (emoji / box-drawing in `list_update`, `subscription_update`, `global_check`, `check_nft`, e.g. `📡 🛠️ ✅ ❌ ⚠️ ➡️ 🧱 🥸 📄` and `━` separators) are **valid UTF-8** and must stay valid UTF-8 — they render correctly on the device (SSH/UTF-8 terminal) and LuCI. They are **not** intentional mojibake.
+- These were once corrupted by a UTF-8→CP1251 double-encode (real UTF-8 bytes read as CP1251 and re-saved as UTF-8), which made them print as `рџ…`/`в”…` garbage; task-004 repaired them. **Never open/save `usr/bin/netshift` in a non-UTF-8 editor or run it through a CP1251 codepage** — doing so reintroduces the `рџ…`/`в”…`/` ` mojibake. Edit it as UTF-8 only.
+
+## 9. New constants
+
+Anything that looks like a port, IP, mark, tag, path, version, URL, or service list goes into `constants.sh` under the right group (`## Common`, `## nft`, `## sing-box`, `## Lists`). Never hardcode it inline. See `project-core.md` §5.
+
+## 10. UCI access patterns
+
+- `config_get var section option [default]` — read an option.
+- `config_get_bool var section option [default]` — read a boolean (0/1).
+- `config_foreach fn type` — call `fn` for each section of `type` (here usually `section`); `fn` receives the section name as `$1`.
+- `config_list_foreach section list fn [extra args...]` — call `fn` for each list item.
+- The CLI runs `config_load "$NETSHIFT_CONFIG"` at startup; after `uci commit` it reloads (`uci commit ...; config_load ...`).
+
+UCI schema lives in `netshift/files/etc/config/netshift` (`settings` section + per-connection sections with `connection_type` = `proxy`/`vpn`/`block`/`exclusion`, and `proxy_config_type` = `url`/`selector`/`urltest`/`outbound`/`subscription`). Changing it is a system-level change (`project-core.md` §4).
+
+## 11. Tests and gates for backend changes
+
+- Run the **`shellcheck`** skill and the **`smoke-tests`** skill before considering a backend change done.
+- Smoke tests live in `tests/entrypoint.sh`. Existing test functions: `test_deps`, `test_syntax`, `test_config`, `test_helpers`, `test_jq_helpers`, `test_config_manager`, `test_sing_box_config`, `test_nft`, `test_diagnostics`, `test_subscription`.
+- **Adding a backend test** means all three of:
+  1. Add a `test_*` function to `tests/entrypoint.sh`.
+  2. Register it in `main()` — add the call to the `all)` branch.
+  3. Add a `case` entry (its short alias) AND list the alias in the "Available:" usage line.
+- Backend changes affecting **config generation** or **subscription parsing** SHOULD add/extend a smoke test (`test_sing_box_config`, `test_config_manager`, `test_jq_helpers`, or `test_subscription`).
+
+## 12. Glob scope confirmation
+
+These rules apply to everything matched by `netshift/files/usr/**` (the CLI, all `*.sh` libraries, and `helpers.jq`).

docs/agent-rules/frontend-luci.md

@@ -0,0 +1,154 @@
+# Agent Rules: Frontend & LuCI
+
+Authoritative rules for the NetShift web UI. Read this before touching any
+frontend or LuCI view code.
+
+**Scope (globs):**
+
+- `fe-app-netshift/src/**/*.ts` — TypeScript source (the real logic).
+- `luci-app-netshift/htdocs/**/*.js` — hand-written LuCI views.
+
+---
+
+## 1. Architecture & build pipeline
+
+- The logic lives in **TypeScript** under `fe-app-netshift/src/`, compiled in
+  `strict` mode (`tsconfig.json`: `strict: true`, `target: ES2020`,
+  `module: ESNext`).
+- `tsup` bundles the single entry `src/main.ts` into
+  `luci-app-netshift/htdocs/luci-static/resources/view/netshift/main.js`
+  (see `tsup.config.ts`: `format: ['esm']`, `outExtension .js`, `clean: false`).
+- The hand-written LuCI views consume the bundle. The entry view
+  `netshift.js` declares `'require view.netshift.main as main'` and uses the
+  exports as `main.*` (e.g. `main.injectGlobalStyles()`, `main.coreService()`).
+  Companion views `section.js`, `settings.js`, plus the thin `dashboard.js` /
+  `diagnostic.js` follow the same pattern.
+
+### CRITICAL: `main.js` is AUTOGENERATED — never hand-edit it
+
+- The bundle is stamped with the banner
+  `// This file is autogenerated, please don't change manually` (set in
+  `tsup.config.ts` `banner.js`).
+- After bundling, `tsup`'s `onSuccess` hook **regex-patches** the file: it
+  rewrites the ESM `export { ... }` block into
+  `return baseclass.extend({ ... })` (see `tsup.config.ts` lines 25-30). This
+  is what makes the bundle loadable as a LuCI `baseclass`.
+- **NEVER hand-edit `main.js`.** Edit the TS source, then run `yarn build`.
+  Any manual edit is destroyed on the next build and will fail CI (build must
+  produce no git diff — see §7).
+
+---
+
+## 2. The barrel rule (most common gotcha)
+
+Anything that must be visible to the LuCI views as `main.*` has to be
+re-exported all the way up the barrel chain to `src/main.ts`.
+
+- `src/main.ts` does `export * from './validators' | './helpers' |
+  './netshift' | './constants'`.
+- `src/validators/index.ts` re-exports each validator module
+  (`export * from './validateIp'`, etc.).
+- **Rule:** any new public API (a validator, helper, constant, or tab) MUST be
+  re-exported up the chain (e.g. `validators/<file>.ts` →
+  `validators/index.ts` → `main.ts`). If you forget the re-export, the symbol
+  will not appear in `main.*` and the LuCI views cannot see it.
+
+**Worked example of the gotcha:** `validateHysteria2Url`
+(`src/validators/validateHysteriaUrl.ts`) is **intentionally NOT** listed in
+`src/validators/index.ts`. It is reached only indirectly via
+`validateProxyUrl` (`validateProxyUrl.ts` imports it and dispatches to it for
+`hysteria2://` URLs). So `main.validateHysteria2Url` does not exist — that is
+deliberate, not a bug. Do not "fix" it by adding it to the barrel unless you
+actually need it exposed.
+
+---
+
+## 3. Backend access boundary
+
+The UI talks to the backend through **only two channels**:
+
+1. LuCI `fs.exec` of the two ACL-gated binaries:
+   - `/usr/bin/netshift`
+   - `/etc/init.d/netshift`
+
+   Both are allow-listed for `exec` in
+   `luci-app-netshift/root/usr/share/rpcd/acl.d/luci-app-netshift.json`
+   (under `read.file`). The same ACL grants `uci` read/write on the
+   `netshift` config and `ubus service list`.
+
+2. Direct `fetch` / WebSocket to the Clash API on `:9090`.
+
+**Rule:** any new shell command the UI needs MUST be implemented as a
+**subcommand of one of those two binaries**, or you must extend both the ACL
+(`acl.d/luci-app-netshift.json`) **and** the backend. Do not invoke arbitrary
+paths via `fs.exec` — they are not ACL-allowed and will be denied by `rpcd`.
+
+---
+
+## 4. Code style (from the config files — non-negotiable)
+
+- **TypeScript:** `strict: true`. No `any`. Prefer functional code and named
+  exports (the barrel relies on named exports).
+- **Prettier** (`.prettierrc`): `printWidth: 80`, `tabWidth: 2`, `semi: true`,
+  `singleQuote: true`, `trailingComma: 'all'`, `bracketSpacing: true`.
+- **ESLint** (flat config `eslint.config.js`): extends
+  `js.configs.recommended` + `typescript-eslint` recommended + `prettier`.
+  `@typescript-eslint/no-unused-vars` is a **`warn`**, with
+  `argsIgnorePattern`, `varsIgnorePattern`, and `caughtErrorsIgnorePattern`
+  all set to `^_`. So any intentionally-unused var/arg/caught-error MUST be
+  `_`-prefixed. CI runs `eslint --max-warnings=0`, so an un-prefixed unused
+  var = warning = CI failure.
+- **LuCI globals** (`E`, `fs`, `uci`, `ui`, `_`, etc.) are declared in
+  `src/luci.d.ts`. Use them; do not redeclare. For DOM built with `E()`, use
+  the `click:` attribute convention for event handlers.
+
+---
+
+## 5. i18n
+
+- Wrap every user-facing string in `_()`.
+- Pass **only string literals** to `_()`. The gettext extractor only sees
+  literal arguments; `_(someVariable)` or `_('a' + b)` will NOT be extracted
+  and will ship untranslated.
+- Locale tooling lives in `package.json` under the `locales:*` scripts
+  (`locales:extract-calls`, `locales:generate-pot`, `locales:generate-po:ru`,
+  `locales:distribute`, with the `locales:actualize` umbrella). Run these to
+  regenerate `.pot`/`.po` after adding strings; do not hand-edit generated
+  catalogs.
+
+---
+
+## 6. Version placeholder
+
+- `src/constants.ts` declares
+  `export const NETSHIFT_LUCI_APP_VERSION = '__COMPILED_VERSION_VARIABLE__';`.
+- At OpenWRT build time, `luci-app-netshift/Makefile` substitutes the literal
+  via `sed -i -e 's/__COMPILED_VERSION_VARIABLE__/$(PKG_VERSION)/g' ...
+  main.js || true`.
+- In dev (where no substitution happens), `normalizeCompiledVersion` turns the
+  raw placeholder into `'dev'`.
+- **Rule:** do not change the literal `__COMPILED_VERSION_VARIABLE__` without
+  also updating the `sed` in the Makefile (and the backend stamp — see
+  `packaging.md`). They must stay in lockstep.
+
+---
+
+## 7. Tests & CI gates
+
+- Vitest config (`vitest.config.js`): `globals: true`, `environment: 'node'`,
+  setup file `./tests/setup/global-mocks.ts` (which identity-mocks `_()` so
+  tests assert on raw strings).
+- Tests live as `.test.js` next to the code under `tests/` directories. Style
+  is table-driven `describe.each`.
+- **New pure logic SHOULD ship a test.**
+- **CI gate** (`.github/workflows/frontend-ci.yml`, runs on PRs touching
+  `fe-app-netshift/**`) runs the steps individually:
+  `yarn install --frozen-lockfile` → `yarn format` then fail on any
+  `git diff` (code must already be formatted) → `yarn lint --max-warnings=0`
+  → `yarn test --run` → `yarn build` then fail on any `git diff`.
+  The convenience local command is `yarn ci`
+  (`format && lint --max-warnings=0 && test --run && build`).
+- **The committed `main.js` MUST be up to date.** Because the build must
+  produce no git diff, always `yarn build` and commit the regenerated bundle
+  together with the TS change.
+- Reference the **`frontend-ci`** skill for the full workflow.

docs/agent-rules/memory/README.md

@@ -0,0 +1,31 @@
+# Agent memory
+
+This folder is the **single source of truth** for per-agent persistent memory,
+shared by both AI toolchains (OpenCode and Claude Code).
+
+OpenCode has no built-in `memory: project` mechanism, so memory here is a plain
+convention: **every agent's prompt instructs it to read its own
+`<agent>.md` file before starting work, and to append durable findings to it
+when it learns something that future runs must not re-discover.**
+
+## Rules for memory files
+
+- One file per agent, named exactly after the agent
+  (`architect-orchestrator.md`, `shell-backend-developer.md`,
+  `luci-frontend-developer.md`, `packaging-ci-engineer.md`,
+  `code-reviewer.md`).
+- Keep each file **under ~200 lines**. It is loaded into the agent's context
+  on every run; bloat costs tokens and dilutes signal.
+- Record only **durable, reusable knowledge**: gotchas, fragile areas,
+  non-obvious conventions, decisions already made, recurring review findings.
+  Do **not** record task-specific narration.
+- These files are **committed to git** so the whole team (and other
+  contributors using AI) benefit.
+- When a fact here is proven wrong or stale, fix it in the same edit — do not
+  let memory drift from reality.
+
+## How the two toolchains share this
+
+Both `.opencode/agent/*.md` and `.claude/agents/*.md` point their agents at
+these files by relative path (`docs/agent-rules/memory/<agent>.md`). There is
+no duplication of memory content — only this one copy.

docs/agent-rules/memory/architect-orchestrator.md

@@ -0,0 +1,410 @@
+# Memory — architect-orchestrator
+
+Durable project knowledge for designing and decomposing NetShift tasks.
+Read this before planning. Append new durable findings; keep under ~200 lines.
+
+## Project shape (verified)
+
+- NetShift = OpenWRT 24.10+ traffic router on top of **sing-box** (>=1.12.0,
+  jq>=1.7.1). Fork of `itdoginfo/podkop`, rebranded to NetShift at 0.8.0. Beta.
+  GPL-2.0-or-later + separate restrictive trademark policy (`TRADEMARK.md`).
+- Three packages, one-way dependency chain:
+  `luci-app-netshift` (LuCI UI, hand-written `.js` views + generated `main.js`)
+  -> `fe-app-netshift` (TypeScript source of `main.js`, built by tsup)
+  -> `netshift` (POSIX ash + jq backend) -> sing-box / nftables / dnsmasq.
+  The UI talks to the backend ONLY via LuCI `fs.exec` of `/usr/bin/netshift`
+  and `/etc/init.d/netshift` (ACL-gated), plus Clash API on :9090.
+
+## Sacred runtime contract (constants.sh — never change casually)
+
+- TProxy inbound `127.0.0.1:1602`; DNS inbound `127.0.0.42:53`; Clash API `:9090`.
+- FakeIP range `198.18.0.0/15`. Marks: FakeIP `0x00100000`, outbound `0x00200000`.
+- nft table `NetShiftTable` (inet); routing table `105 netshift`.
+- Required versions `SB_REQUIRED_VERSION=1.12.0`, `JQ_REQUIRED_VERSION=1.7.1`.
+
+## Data flow (start_main in usr/bin/netshift)
+
+check_requirements -> migration (currently no-op) -> validate services ->
+br_netfilter_disable -> NTP sync -> subscription cache prep -> route table + nft
+base -> sing_box_configure_service -> sing_box_init_config (build JSON) ->
+save+`sing-box check` -> cron jobs -> start sing-box -> dnsmasq_configure ->
+`list_update &` (background heavy list download).
+
+## Quality gates a task must pass before "done"
+
+- Backend (`netshift/files/**`): `shellcheck` skill (severity error) +
+  `smoke-tests` skill (tests/entrypoint.sh `all`).
+- Frontend (`fe-app-netshift/**`): `frontend-ci` skill (`yarn ci`) AND the
+  committed `main.js` must be regenerated (build must leave no git diff).
+- Packaging/CI changes: smoke-tests at minimum; verify both ipk and apk paths.
+
+## Decomposition policy
+
+- Map subtasks to the right developer agent:
+  backend/shell/jq/sing-box/nft/dnsmasq/UCI -> `shell-backend-developer`;
+  TS source / LuCI views / validators / i18n -> `luci-frontend-developer`;
+  Makefile / Docker / SDK / workflows / tests harness / install.sh ->
+  `packaging-ci-engineer`.
+- A change touching the TS source almost always also requires a rebuild of
+  `main.js` (frontend dev handles via `yarn build`). Flag this in the spec.
+- "System-level" changes (nft, routing, config schema, ports/marks, dnsmasq,
+  packaging) must be verified across the whole chain, not one file.
+- Never allow a commit without a passed code-reviewer verdict. Never skip the
+  relevant gate. Humans commit manually — agents never auto-commit.
+
+## Known latent bugs / landmines (don't reintroduce; fix only if in scope)
+
+- `usr/bin/netshift` dispatches `main)` and `check_sing_box_logs)` but NO such
+  functions are defined — dead/broken dispatch.
+- nft proxy chain hardcodes `127.0.0.1:1602` instead of using the constants
+  (duplication; changing the constant won't change the rule).
+- VPN `domain_resolver` uses `$dns_server` (undefined in scope) instead of
+  `$domain_resolver_dns_server`.
+- Frontend `runFakeIPCheck` has inverted-looking allGood/atLeastOneGood logic.
+- Diagnostic strings contain intentional CP1251 mojibake (emoji/box-drawing) —
+  preserve byte sequences when editing.
+- `validate_subscription_file` (helpers.sh) only checks `.type` is NOT in
+  {selector,urltest,direct,dns,block}. A body whose outbounds lack `.type`
+  entirely (e.g. a single Xray-config OBJECT using `.protocol`) passes as
+  "valid" → bypasses the fallback normalizer and later fails `sing-box check`.
+  An Xray ARRAY is `type=="array"` and correctly falls through to normalize.
+  Watch this when adding any pre-normalize validate gate.
+
+## Subscription pipeline facts (verified 2026-06)
+
+- Fallback chain in `download_subscription_into_cache` (usr/bin/netshift):
+  validate raw body FIRST, only then `normalize_subscription_to_singbox`
+  (base64 / plaintext URI list / Xray-JSON). UA fallback wraps the whole loop:
+  it probes `SUBSCRIPTION_USER_AGENT_CANDIDATES` (constants.sh) when no UA is
+  configured, caches the winner in `<section>.user_agent` (atomic .tmp.$$+mv).
+- New per-section UCI option `subscription_user_agent` is read but NOT yet in
+  the UCI schema / LuCI / ACL. Degrades gracefully (empty ⇒ auto). Treat any
+  promotion to a real UI knob as a system-level change (schema + LuCI + i18n).
+- `xray_json_to_uri_lines` converts Xray client configs (object|array) to share
+  URIs; emits ONLY keys the facade reads (type/path/host/mode/serviceName/
+  security/sni/alpn/fp/pbk/sid/flow); drops vmess (counted by
+  `xray_json_count_unsupported`) and dialerProxy-chained outbounds; dedups on
+  the connection part. No-regex jq + busybox-safe sed pre-gate.
+
+## Core-switch (sing-box <-> extended) failure — DIAGNOSED on real hardware 2026-06
+
+- SYMPTOM: switching stock->extended fails; on the router the new ~79MB binary
+  sits at /usr/bin/sing-box but with perms `rw-------` (NOT executable), the
+  tmpfs backup + downloaded archive remain, sing-box won't run.
+- ROOT CAUSE: **rpcd timeout**. rpcd runs with `-t 30` (30s). The UI calls
+  `component_action sing_box install_extended` SYNCHRONOUSLY via LuCI fs.exec.
+  Download (~29MB over a slow/proxied link) + gzip extract of the 50MB binary
+  (measured **13s just for extract** on aarch64 cortex-a53) exceeds 30s, so rpcd
+  KILLS the process mid-flight — AFTER `tar -O > /usr/bin/sing-box` (file written
+  `rw-------` under the context umask 0077) but BEFORE `chmod 0755` + the
+  `LD_LIBRARY_PATH=/usr/lib sing-box version` validation. Hence the un-chmod'd
+  binary, leftover backup/archive, no cleanup.
+- DISPROVEN earlier guesses: (a) NOT a disk-space issue (repro'd with free
+  space). (b) NOT the missing-LD_LIBRARY_PATH theory — the extended binary runs
+  `sing-box version` fine WITHOUT LD_LIBRARY_PATH (libcronet only needed at
+  runtime for naive); `chmod 0755` itself works under umask 0077. The code's
+  chmod/validate is correct; it just never gets to run.
+- FIX DIRECTION: make core-switch ASYNCHRONOUS — has `component_action_async` 
+  (writes output to a file, forks the work) +
+  `component_action_status` (UI polls). NetShift's updater is synchronous and has
+  no async/status path. Port that model: fork the install, return immediately,
+  poll status; UI shows progress instead of hitting the 30s rpcd wall.
+- Secondary hardening to fold in: chmod 0755 BEFORE validation is already there
+  but ordering/robustness should survive interruption; also rulesets in
+  /tmp/sing-box/rulesets were `rw-------` (umask 0077) — sing-box could still read
+  them as root, not the failure cause, but worth normalizing.
+- Manual recovery that works: `chmod 0755 /usr/bin/sing-box` (the downloaded
+  extended binary is valid), `rm -rf /tmp/netshift-sbext.*`, restart netshift.
+- Router access for testing: `ssh root@192.168.1.1` (no password). aarch64,
+  OpenWrt 24.10.5, overlay 60.9M (16.5M free), /tmp tmpfs 117M. scp does NOT work
+  (no sftp-server) — push scripts via `echo <base64> | base64 -d > f` over ssh.
+
+## Core-switch async fix (task-007) — on-device verified 2026-06; SECOND bug found
+
+- task-007 async model WORKS on real hardware: `component_action_async` returns
+  in 0s with a job_id (no more rpcd 30s kill), `component_action_status` polling
+  goes running->finished cleanly. The PRIMARY bug (synchronous timeout) is fixed.
+- BUT live-testing exposed a SECOND, deeper bug in `updates_install_sing_box_stable`
+  (extended->stock): it has NO backup/rollback (unlike the extended path) AND the
+  whole switch happens while NetShift's nft tproxy + dnsmasq redirect are STILL
+  active. Sequence that bricked the router:
+  1. install_stable removes/replaces the extended binary, then `opkg/apk install
+     sing-box` needs working internet — but the only internet was THROUGH the now
+     -dead VPN. opkg fails with "Operation not permitted" + DNS timeout (the nft
+     kill-switch sends marked traffic to a dead sing-box).
+  2. Net result: /usr/bin/sing-box GONE, no rollback, router has no working core
+     and can't fetch one (extended path also fails: GitHub unreachable w/o VPN).
+- This is a CLASSIC kill-switch deadlock: you can't download a new core because
+  the old core (that provided connectivity) is gone.
+- RESCUE that works: `/etc/init.d/netshift stop` (tears down nft/dnsmasq so direct
+  internet returns) -> set a real resolver -> `opkg update && opkg install
+  sing-box` -> `/etc/init.d/netshift restart`. Verified: restored stock 1.12.22,
+  sing-box running.
+- DESIGN IMPLICATION for the stable-rollback path (future task): before
+  install_stable, KEEP a backup of the current (extended) binary on tmpfs and
+  RESTORE it if the package install fails (so a failed downgrade never leaves the
+  router core-less) — mirror the extended path's backup/restore. Also consider
+  tearing down the redirect (or a temporary direct route) during a core swap so
+  the package manager can reach the feeds. The extended->stock path fundamentally
+  needs connectivity that the dead VPN may have been providing.
+- Router note: stock sing-box install also drops `/etc/config/sing-box-opkg` and
+  `/etc/sing-box/config.json-opkg` (conffile conflicts) — harmless, NetShift owns
+  its own config path.
+
+## sing-box-extended capability map (researched 2026-06)
+
+- NetShift ALREADY installs sing-box-extended: `updater.sh` pulls
+  `shtorm-7/sing-box-extended`; `is_sing_box_extended` gates features (today only
+  xhttp transport in the facade). So the runtime platform for extended protocols
+  exists; what's missing is config GENERATION (jq cm_*/cf_*), UCI schema, UI.
+- Our facade currently builds only: socks4/4a/5, vless, ss, trojan, hysteria2.
+  Transports: ws, grpc, httpupgrade, xhttp. No endpoint/wireguard support at all
+  (`sing_box_cm_add_*_outbound` has no wireguard/endpoint).
+- Extended (repo `sing-box-extended-extended/option/*.go`) adds many: anytls,
+  tuic, shadowtls, wireguard(+Amnezia/AWG), warp(+Amnezia), masque, mieru,
+  mtproxy, naive, openvpn, ssh, tor, trusttunnel, sudoku, bond, failover, vpn,
+  vmess; transports incl. v2ray kcp/quic, simple-obfs, sip003.
+- Amnezia WG schema (sing-box 1.12 `endpoint` model): an `endpoint` with
+  `"type":"wireguard"`, `private_key`, `address` (listable prefix), `peers[]`
+  (address/port/public_key/pre_shared_key/allowed_ips/persistent_keepalive...),
+  plus nested `"amnezia": { jc,jmin,jmax,s1..s4, h1..h4 (ranges), i1..i5, j1..j3,
+  itime }`. WARP = same WG core + `amnezia` + Cloudflare `profile`/`reserved`.
+- Feasibility tiers for porting to our ash+jq backend:
+  * EASY (pure-JSON outbound, no extra daemon, just a new cm_* + cf_* + URI/UCI
+    parse): tuic, anytls, shadowtls, vmess, naive, hysteria(v1). These mirror the
+    existing vless/trojan/hysteria2 pattern.
+  * MEDIUM: wireguard + Amnezia/AWG and WARP — needs the `endpoints[]` array
+    (new section in config skeleton, route ties to endpoint tag) + key/peer
+    parsing; input format must be decided (awg:// vs wg-conf vs UCI fields).
+  * HARD / likely out of scope: openvpn, mieru, masque, mtproxy(outbound),
+    trusttunnel, sudoku, tor, ssh, bond/failover/vpn groups — bespoke schemas,
+    some need extra config files/daemons; high test surface.
+- Hard dependency for ANY of these: the user must be running the extended build;
+  gate generation behind `is_sing_box_extended` and fail safe (warn + skip) when
+  stock sing-box is installed, exactly like xhttp does today.
+
+## sing-box-extended version diagnostic (task-013 — done 2026-06-05)
+
+- BUG: `check_sing_box` (usr/bin/netshift ~3276) showed "❌ version not compatible"
+  on the extended core. TWO coupled defects:
+  1. `awk '{print $3}'` on `sing-box version 1.13.12-extended-2.3.2` → patch via
+     `cut -d. -f3` = `12-extended-2` (non-numeric) → `[: bad number`.
+  2. The compare `if [ A ] || [ B ] && [ C ] || [ D ] && [ E ] && [ F ]` was
+     UNGROUPED. POSIX `&&`/`||` are EQUAL-precedence, LEFT-associative, so it
+     parses `(((((A||B)&&C)||D)&&E)&&F)` — the trailing E/F gate EVERY branch,
+     so 1.13.x AND 2.0.0 evaluate as not-compatible even with a numeric patch.
+- FIX (Variant 2, operator-chosen): strip suffix `version=${version%%-*}` (gives
+  honest semver; extended author only bumps the trailing `-extended-X.Y.Z`,
+  leading major.minor.patch is true upstream sing-box) + regroup each AND-term in
+  `{ ...; }`. Kept threshold 1.12.4 + printed text. Did NOT touch check_requirements
+  (uses sort -V, already extended-safe). 1-file change, gates green.
+- LANDMINE for future tasks: any `[ ] || [ ] && [ ]` chain in this repo without
+  `{ ...; }` grouping is suspect — equal precedence means trailing AND-terms leak
+  into prior OR-branches. Group every AND-term. (My first decomposition wrongly
+  assumed the strip alone fixed it; the dev caught the precedence bug on live
+  reasoning — TRUST dev "second defect" flags, re-derive the truth table myself.)
+- Extended core real output (operator hardware, captured for the epic): version
+  `1.13.12-extended-2.3.2`, Tags include `with_quic,with_wireguard,with_utls,
+  with_masque,with_mtproxy,with_openvpn,with_trusttunnel,with_sudoku,
+  with_naive_outbound,with_gvisor`. So the shtorm-7 build SHIPS the build-tags for
+  nearly all of epic Tiers 1–3 (tuic/hysteria need with_quic ✅, AWG needs
+  with_wireguard ✅, sudoku/trusttunnel/openvpn ✅) — CX-4 build-tag uncertainty is
+  largely resolved EMPIRICALLY for this build; still gate generation behind
+  is_sing_box_extended + tolerate a per-protocol `sing-box check` rejection.
+- SECOND hardcode of the version threshold confirmed: check_sing_box hardcodes
+  "1.12.4" (major/minor/patch literals + text) while SB_REQUIRED_VERSION=1.12.0 in
+  constants.sh. Known rassinkhron; left as-is per operator (out of task-013 scope).
+
+## Subscription keyword filter — Cyrillic case bug (task-010, found on hardware 2026-06)
+
+- REAL bug (not version skew): the keyword filter's "case-insensitive" claim only
+  holds for ASCII. `sing_box_cf_prepare_subscription_batch`
+  (sing_box_config_facade.sh:542/543/567) uses jq `ascii_downcase`, which does
+  NOT lowercase Cyrillic (or any non-ASCII).
+- FIX: replace the 3 `ascii_downcase` in prepare_subscription_batch with an inline
+  jq `def ucfold` (codepoint arithmetic, NO Oniguruma): ASCII A-Z (65–90)+32,
+  Cyrillic А-Я (1040–1071)+32, Ё(1025)->ё(1105). Apply to BOTH the keyword list
+  and the node name. `explode`/`map`/`implode`/`index` all work on the device jq.
+  (Это inline — этот jq-вызов НЕ импортирует helpers.jq.)
+- rejected-hash (`<section>.rejected`, md5 of body) can wedge a retry storm if a
+  STUB body once got cached as rejected; it self-clears once a real body downloads
+  (return 0 path rm's it). Not the root cause here but amplified the symptom.
+
+## Workflow facts
+
+- Contribution gating: `CODEOWNERS=@yandexru45`; PRs accepted only after Telegram
+  coordination with authors (README). Reflect this in `/describe` output.
+- **Frontend yarn trap (verified 2026-06):** repo `fe-app-netshift/yarn.lock` is
+  CLASSIC yarn v1 format; there is NO `packageManager` pin and NO `.yarnrc.yml`.
+  A local corepack yarn 4.x will try to MIGRATE on `yarn install`, polluting the
+  tree with a 3000+ line `yarn.lock` rewrite + untracked `.yarn/` and
+  `.yarnrc.yml`. These are NOT deliverables — discard before commit
+  (`git checkout -- fe-app-netshift/yarn.lock`; rm `.yarn/`/`.yarnrc.yml`). To
+  verify the gate independently without polluting, run the tools directly from
+  `node_modules/.bin` (prettier/eslint/vitest/tsup) instead of `yarn install`.
+  Tell frontend devs to leave yarn.lock alone.
+- The frontend-ci `main.js` no-diff check: a TYPE-ONLY change in TS source
+  (e.g. adding optional fields to a `types.ts` interface) produces NO main.js
+  diff — that is expected/correct, not a missed rebuild.
+
+## Subscription keyword filter (issue #5, task-002/003 — done 2026-06)
+
+- Backend filter lives in `sing_box_cf_prepare_subscription_batch`
+  (sing_box_config_facade.sh): one jq pass between candidate-select and the
+  static-unsupported filter, BEFORE tag dedup + sing-box check. Covers native +
+  all fallback (base64/URI/Xray) bodies and both selector branches automatically.
+- UCI options (cross-layer contract, verbatim): `subscription_filter_include_keywords`
+  (whitelist) / `subscription_filter_exclude_keywords` (blacklist), both UCI
+  `list`. Read in the `subscription)` branch via `config_list_foreach`.
+- Semantics: include=OR (empty⇒keep all), exclude=OR(drop), SUBSTRING,
+  ASCII-case-insensitive (`ascii_downcase`), byte-exact for emoji/Cyrillic.
+  jq: NOTE `include`/`exclude` are RESERVED jq words — devs used `$inc`/`$exc`;
+  matching must use `. as $kw` inside any/all to avoid the `.`-after-pipe rebind.
+- Empty-after-filter ⇒ existing fail-safe `mark_subscription_outbound_unavailable`
+  + warn (NO exit 1). `skipped` stays "statically unsupported" (compute `$total`
+  AFTER the keyword filter, not before).
+- UI: two `form.DynamicList` in `section.js` after `subscription_group_by_countries`,
+  rmempty=true, NO validator (keep emoji/space verbatim); `string[]?` fields on
+  `ConfigProxySubscriptionSection` in types.ts; ru/en via locale tooling.
+
+## PR review workflow + PR #11 findings (review-001, 2026-06-06)
+
+- Reviewing an external PR (no `gh` CLI installed): fetch via API
+  `curl https://api.github.com/repos/yandexru45/netshift/pulls/N` (meta),
+  `.../files` (per-file stats), and `-H "Accept: application/vnd.github.v3.diff"`
+  for the raw diff. Then `git fetch origin pull/N/head:pr-N` to get a local ref
+  diffable vs `main`. Workspace `.pr-review/` + `*.txt` are gitignored (untracked).
+- Decompose review by LAYER (backend / frontend+i18n / tests-packaging) into
+  separate diff txt files; launch one `explore` subagent per layer IN PARALLEL
+  (layers don't share files), then consolidate with the formal `code-reviewer`.
+  Give each subagent an architect "systemic notes" file of HYPOTHESES to verify.
+- **nftables landmine (VERIFIED on nft v1.1.3):** `tproxy ip6 to <addr>:<port>`
+  REQUIRES bracketed `[addr]:port`. The unbracketed form (e.g. `::1:1603`) PASSES
+  `nft -c` AND `sing-box check`, but nft normalizes it to a BARE address with NO
+  port (`::1:1603` -> `[::0.1.22.3]`). Only on-device / `unshare -rn nft -f` +
+  `nft list ruleset` reveals it. IPv4 `addr:port` is fine unbracketed; v6 is not.
+- **Local nft verification trick (no root):** `unshare -rn nft -c -f file` /
+  `unshare -rn sh -c 'nft -f f && nft list ruleset'` gives netlink in a private
+  netns so you can load+inspect normalized rules. Plain `nft -c` fails with
+  "cache initialization failed: Operation not permitted" without it.
+- PR #11 ("Синхронизация с netshift", spgsroot, +2314/-1364, 23 files) verdict:
+  **REQUIRES CHANGES**. Doc at `.pr-review/REVIEW-pr-11.md` (canonical copy would
+  be `docs/tasks/sync-netshift-review-001.md`). Headline = IPv6 + DoH-block +
+  global_proxy + sing-box health monitor + check_proxy rework.
+  * BLOCKER B-01: unbracketed v6 tproxy rule (above).
+  * Majors: nft model shift (mangle now marks ALL interface traffic, split moved
+    to sing-box route rules) — `mangle_output` lost router-originated @common/
+    fakeip marking (regression); `@netshift_subnets`/@common still populated each
+    `list_update` but matched by NO rule (dead import path); 8x `SUBNETS_*_V6`
+    dead constants; `start()` spawns `monitor_sing_box` with no pidfile+kill-0
+    guard (orphan leak); over-permissive `validateIPV6` regex (accepts `:::`,
+    `1::2::3`, etc.) shared by subnet+dns validators, no negative tests; 3 new
+    flag descriptions concat'd inside `_()` -> ship untranslated.
+  * GOOD: generated `main.js` is a faithful DRIFT-FREE rebuild (CI no-diff should
+    pass); NO Oniguruma jq; UTF-8 emoji intact; i18n catalogs machine-consistent.
+  * Coverage gap: the nft model shift has NO smoke test (test_global_proxy only
+    checks sing-box route-rule SHAPE; test_nft byte-identical to base) — that's
+    why B-01 slipped. Any nft-rule PR should add an `nft list ruleset` assertion.
+
+## PR #11 fix-to-perfect cycle (2026-06-06, after operator merged the PR)
+
+- Operator merged PR #11 to main, then asked to fix everything to perfection.
+  Decomposed the review-doc issues into 3 task specs (docs/tasks/task-014 backend,
+  -015 frontend, -016 packaging) + delegated to the 3 dev subagents, ran the
+  dev<->code-reviewer loop per layer until all APPROVED. NOTE: `docs/tasks/` is
+  gitignored (line 7 `docs/tasks`), so task specs are session artifacts (like
+  .pr-review/), not committed — that's by project design (only TEMPLATE-*.md are
+  force-tracked).
+- Operator design decisions for the nft model shift: B-02=A (router-originated
+  traffic stays DIRECT in the new mark-everything-in-prerouting model; document
+  only, don't restore mangle_output marking) and B-03/B-04=A (remove the dead
+  @netshift_subnets populate path + dead SUBNETS_*_V6). Rule: dead-code removal
+  for a SET requires first PROVING every populated source is carried by a sing-box
+  rule_set; the dev produced a coverage map (community->$SRS_MAIN_URL/<svc>.srs,
+  user/local/remote subnets->rule_sets). DISCORD set is RETAINED (it has a
+  dport-restricted mangle rule `udp dport {19000-20000,50000-65535}` that a
+  sing-box route rule cannot express). M1/M2 left as non-blocking follow-ups
+  (orphaned rulesets.sh helpers + unused IPv4 SUBNETS_* under SC2034).
+- **dnsmasq "we-own-it" guard landmine (B-08):** a guard that infers netshift
+  ownership from the PRESENCE of `netshift_*` BACKUP markers is WRONG, because
+  `backup_dnsmasq_config_option` only writes a marker when the ORIGINAL value was
+  non-empty. On stock/default dnsmasq (empty server/noresolv/cachesize) NO markers
+  exist, so on the redundant `dnsmasq_configure force` path (monitor recovery /
+  double-start) the guard flips false, re-runs backup, and records netshift's OWN
+  live values (noresolv=1/cachesize=0) as the "backup" -> restore later sets
+  noresolv=1/cachesize=0 instead of defaults 0/150 -> router DNS broken after stop.
+  FIX: an explicit unconditional sentinel `netshift_configured=1` set in
+  dnsmasq_configure, gating the short-circuit, cleared in dnsmasq_restore.
+- **nft v6 NEGATIVE-guard test landmine:** the buggy unbracketed `::1:1603`
+  normalizes DIFFERENTLY per nft build: `[::0.1.22.3]` on nftables v1.1.3 (WSL),
+  but `[::1:1603]` on OpenWRT 24.10.6's nft (the smoke container). So a negative
+  grep for `::0` OR even `\[::0` is a DEAD always-passing assertion in the smoke
+  env. ROBUST pattern: `grep 'tproxy ip6 to \[' | grep -qv '\[::1\]:1603'` (any
+  bracketed dest that ISN'T the correct one). Always self-prove a regression guard
+  by temporarily reintroducing the bug and confirming the test FAILS.
+- Environment (WSL2 Debian 12): Docker daemon socket-activation can leave a
+  self-referential symlink (`/var/run/docker.sock -> /run/docker.sock` where
+  /var/run IS /run); fix = `sudo rm -f /run/docker.sock; sudo systemctl restart
+  docker.socket docker.service`. shellcheck not installed -> grab the static
+  binary to ~/.local/bin (koalaman release tar.xz). yarn is classic 1.22.x via
+  corepack (safe, no yarn.lock migration); deps install clean with --frozen-lockfile.
+- FINAL integrated gates after the cycle: shellcheck (error) clean; yarn ci 439
+  tests pass (was 395) + main.js idempotent rebuild (two builds byte-identical);
+  smoke `all` = 84 passed / 0 failed (was 81; +3 nft v6 regression assertions);
+  whole-chain `unshare -rn` confirms v6 tproxy normalizes to [::1]:1603. All 3
+  layers code-reviewer APPROVED. Ready for human commit (agents never auto-commit).
+
+## Component Manager feature (task-017 backend + task-018 frontend, 2026-06-06)
+
+- New LuCI tab "Component Manager" (RU "Менеджер компонентов"): 3 cards
+  (NetShift / sing-box stock / sing-box extended) with installed version shown
+  immediately + on-demand "Check update" + status badges + update/core-switch/
+  self-update actions. Core-switch MOVED out of Diagnostics into here.
+- Backend (task-017, updater.sh): two NEW component_action sub-cases (the
+  dispatcher is component_action() :1272, a `case "$comp:$action"`; that is the
+  ONLY extension point — component_action_async/_status are component-agnostic,
+  no dispatcher change for new actions). Added `sing_box:check_update_stable`
+  (sync) + `netshift:self_update` (async via component_action_async). Self-update
+  = Variant A: targeted pkg upgrade (download release .ipk/.apk + pkg_install),
+  NOT install.sh (interactive `read`). MUST mirror the updates_install_sing_box_
+  extended epilogue (:878-903): reset UPDATES_HEAL_* -> ensure_connectivity
+  "extended" -> _core to /tmp file + rc -> ALWAYS updates_restore_after_swap ->
+  re-emit JSON -> return rc. NEVER exit on recoverable fail (echo failure JSON +
+  return nonzero). Minimal /etc/config/netshift backup. RU i18n only if installed.
+- SELF-REPLACEMENT (critical, verified safe): the netshift pkg replaces the very
+  /usr/bin/netshift running the worker. The async fork runs `"$0" component_action
+  netshift self_update` in `( trap '' HUP; ... ) &`; busybox ash holds the whole
+  script in memory, and updates_write_finished_job_state runs in the SAME subshell
+  AFTER the worker returns — both complete from memory despite the on-disk swap.
+  RULE: the self_update worker must contain NO exec / NO "$0" / NO re-invoke of
+  /usr/bin/netshift / NO updates_restart_netshift after pkg_install. (Only
+  /etc/init.d/netshift start via restore, AFTER install, as a fresh process — ok.)
+- updater.sh does NOT source install.sh -> re-implement the tiny pkg helpers
+  locally with the `updates_` prefix (updates_pkg_is_apk/_install_file/
+  _is_installed/_candidate_version). pkg output parsed with cut/awk/grep (no
+  Oniguruma). Stock candidate via opkg info/list or apk list; >= compare via
+  is_min_package_version (sort -V) on leading semver ${v%%-*}.
+- STABLE cross-layer contract: check_update_stable -> {success,current_version,
+  latest_version,status:"latest"|"outdated"|"not_installed"}; self_update finished
+  -> {success,version,message}; versions from get_system_info (netshift_version,
+  netshift_latest_version, sing_box_version "not installed" when absent,
+  sing_box_extended 0|1). ACL already allows fs.exec /usr/bin/netshift -> no ACL
+  change for component_action.
+- FRONTEND landmine caught by review (C1): NetShift's "Check update" has NO
+  backend check action (there is no netshift:check_update). NetShift latest comes
+  ONLY from get_system_info.netshift_latest_version. A card whose "latest" comes
+  from a DIFFERENT source than a sibling MUST use a DISTINCT action kind
+  (`check_netshift`, no backendAction) that refreshes systemInfo — never route it
+  through the sing-box check method or write a sing-box result into its check
+  slice. Generalize: when mirroring a multi-card update pattern, verify EACH
+  card's check actually targets ITS OWN backend source.
+- Lenient mid-job polling for self_update: the poll's fetchStatus swallows exec/
+  parse errors and returns synthetic {running:true} (NOT null) so the mid-job
+  binary swap isn't misreported as failure; scoped strictly AFTER a job_id is
+  obtained (a failed START still surfaces), bounded by MAX_POLLS; success ->
+  warning toast + window.location.reload().
+- FINAL gates: shellcheck clean; yarn ci 465 tests; main.js idempotent (two builds
+  byte-identical) + no yarn pollution + i18n catalogs byte-identical (fe<->luci);
+  smoke all = 101 passed / 0 failed (84 -> +17 new: stablecheck x4 + selfupdate
+  x13). Both layers code-reviewer APPROVED (backend 1st pass; frontend after a
+  C1/S1 fix round). Ready for human commit.

docs/agent-rules/memory/code-reviewer.md

@@ -0,0 +1,66 @@
+# Memory — code-reviewer
+
+Reusable review findings and check focus for NetShift. Read before reviewing;
+append recurring findings; keep under ~200 lines.
+
+## What to check (in priority order)
+
+1. **Architecture / layer direction**: UI -> backend (via fs.exec of the two
+   allowed binaries) -> sing-box/nft/dnsmasq. No layer skips another. UI must
+   not reimplement backend logic; backend must not hardcode what belongs in
+   `constants.sh`.
+2. **Runtime contract intact**: ports/marks/paths (1602, 127.0.0.42:53, :9090,
+   198.18.0.0/15, marks 0x100000/0x200000, `NetShiftTable`, `105 netshift`)
+   unchanged unless the task explicitly says so and the WHOLE chain is updated.
+3. **Backend shell correctness**: `# shellcheck shell=ash`; all `local`; correct
+   function prefix; `$config` echo-and-reassign threading; **no jq regex**
+   (test/match/sub/gsub) — flag any as CRITICAL; `fatal` log followed by
+   `exit 1`; atomic write + `sing-box check`; new constants in `constants.sh`.
+4. **Frontend correctness**: did they edit TS source (not `main.js` by hand)?
+   Did they rebuild so `main.js` matches (no stray diff)? New public API
+   re-exported up the barrel to `main.*`? Unused vars `_`-prefixed? `_()` around
+   new user-facing literals? No `any`?
+5. **Test coverage / gates**: backend config-gen or subscription changes should
+   add/extend a smoke test; new pure frontend logic should ship a vitest
+   `.test.js`. Confirm the relevant gate (shellcheck / smoke-tests / yarn ci)
+   was run.
+6. **Packaging**: respect the intentional ipk `v`-prefix vs apk-raw
+   inconsistency; don't break the underscore->dash rename; version placeholder
+   stamping intact.
+
+## Output
+
+- Write the review to `docs/tasks/<task-name>-review-001.md` using
+  `docs/tasks/TEMPLATE-review.md`.
+- Verdict vocabulary: `APPROVED` / `APPROVED WITH CONDITIONS` /
+  `REQUIRES CHANGES`. ID-tag issues (C1 critical, S1 significant, M1 minor) and
+  cite exact `file:line`.
+- No flattery. No speculation — report only what you can verify. Every problem
+  gets a concrete recommendation.
+
+## Recurring findings to watch for
+
+- jq regex functions sneaking in (CRITICAL on OpenWRT jq).
+- `fatal` log without a following `exit 1`.
+- Hand-edited `main.js` or a `main.js` that doesn't match a fresh build.
+- New validator/helper not re-exported -> invisible to `main.*`.
+- Hardcoded ports/IPs/paths instead of `constants.sh` references.
+- Routing code that ignores `subscription_outbound_is_unavailable` (traffic
+  leak when a subscription is down).
+- Scope creep: unrelated file churn (e.g. lockfile churn) flagged as Minor.
+- Diagnostic strings in `usr/bin/netshift` are valid UTF-8 emoji/box-drawing —
+  must stay UTF-8, never CP1251 (task-004 fixed a double-encode). For
+  mojibake-repair reviews, prove ASCII-byte preservation byte-safely (Python:
+  decode HEAD blob vs working tree, strip `[^\x00-\x7F]` per line, expect 0
+  mismatched lines); beware PowerShell text pipelines which produce false UTF-16
+  diffs.
+
+- base64 share-link decode vs `sing_box_cf_add_proxy_outbound` `url_decode` (facade:65): the facade runs `url_decode` (+>space, %XX>byte) on the whole URL before the scheme case. Any case that base64-decodes the ENTIRE payload (vmess, future tuic/etc.) must use the RAW pre-url_decode link <20> standard base64 contains '+'. The ss) case escapes this only because it decodes a short method:password userinfo. Beware synthetic test keys that avoid '+' masking this (false green).
+
+- For protocol validators that base64-decode a whole body (vmess, future tuic/etc.): the '+'-regression is real only if the dispatcher preserves '+'. validateProxyUrl only .trim()s, so '+' survives at the boundary <20> a green direct-call '+' test is sufficient evidence; a dispatcher-level '+' assertion is the stronger guard.
+
+- Wrapper/core split for always-run cleanup (task-009 core-switch): verify the public wrapper captures core stdout to a temp file + rc, then UNCONDITIONALLY calls restore/cleanup before re-emitting JSON and return rc; confirm the worker runs without set -e (else a non-zero core rc could skip trailing cleanup) and that _*_core never exits. For never-end-core-less rollbacks, confirm the tmpfs backup happens BEFORE the package manager/extract touches the binary and is dropped ONLY on the confirmed-good path; strongest test deletes the live mock binary on simulated failure and asserts original bytes restored.
+
+- Frontend barrel exposure: anything added to src/helpers/index.ts (or any export* barrel reaching main.ts) AND actually used appears in the generated main.js baseclass.extend block as a main.* symbol; unused re-exports get tree-shaken. So internal-only helper + added to barrel + used = it WILL leak to main.*. To keep a helper truly internal, place it in the consuming module, not the barrel.
+
+- OpenWrt jq ascii_downcase only folds ASCII A-Z; case-insensitive matching on Cyrillic/Unicode names needs an inline codepoint fold (explode/map/implode: ASCII 65-90 +32, Cyrillic 1040-1071 +32, Yo 1025->1105). When reviewing such a fold: (a) already-lowercase ranges excluded (no double-fold), (b) def before first use when the program does NOT import helpers.jq, (c) a pure-emoji-keyword exact-match test proves non-folded codepoints pass through unchanged on both sides. (task-010)

docs/agent-rules/memory/luci-frontend-developer.md

@@ -0,0 +1,424 @@
+# Memory — luci-frontend-developer
+
+Durable frontend (TypeScript / LuCI) knowledge. Read before implementing;
+append findings; keep under ~200 lines.
+
+## The generated bundle (most important)
+
+- `luci-app-netshift/htdocs/luci-static/resources/view/netshift/main.js` is
+  **autogenerated by tsup** from `fe-app-netshift/src/**`. Banner: "This file is
+  autogenerated, please don't change manually." NEVER hand-edit it. Edit TS
+  source, then `yarn build`. CI fails if the committed `main.js` differs from a
+  fresh build (`git diff --exit-code` after build).
+- tsup `onSuccess` regex-patches the ESM `export { ... }` block into
+  `return baseclass.extend({ ... })` so LuCI can load it as a baseclass module.
+  An unusual export shape could break that regex.
+
+## Barrel / export reachability (recurring gotcha)
+
+- Hand-written views consume the bundle as `main.*` via
+  `'require view.netshift.main as main'`. A new public API
+  (validator/helper/constant/tab) reaches the views ONLY if it is re-exported
+  up the barrel chain to `src/main.ts`.
+- `validateHysteria2Url` (in `validateHysteriaUrl.ts`) is intentionally NOT in
+  `validators/index.ts` — only `validateProxyUrl` is exported; it dispatches to
+  the per-scheme validators internally. Mirror that pattern: export the
+  dispatcher, not necessarily every leaf.
+- Other helpers (prettyBytes, showToast, normalizeCompiledVersion, etc.) are
+  imported by direct path, not via barrel. Check before assuming barrel.
+
+## Backend access
+
+- Only `/usr/bin/netshift` and `/etc/init.d/netshift` are ACL-allowed for
+  `fs.exec` (acl.d/luci-app-netshift.json). A new shell command must be a
+  subcommand of one of those, else extend the ACL + backend. Plus Clash API on
+  `ws://<host>:9090` and `http://<host>:9090/ui`.
+
+## Style / CI
+
+- `yarn ci` = `format && lint --max-warnings=0 && test --run && build`.
+  No-diff enforcement (format + build) lives in `frontend-ci.yml` via
+  `git diff --exit-code`. Run the `frontend-ci` skill before handing back.
+- Prettier: 2-space, single quotes, semicolons, trailing-comma all, width 80.
+- ESLint: `@typescript-eslint/no-unused-vars` is a WARNING with `^_` ignore, and
+  CI is `--max-warnings=0` => unused vars MUST be `_`-prefixed (`_e`, `_err`).
+- strict TS, no `any`, functional components, named exports.
+- LuCI globals (E, fs, uci, ui, _) are in `src/luci.d.ts` (no import). E()
+  handlers use the `click:` attribute (not `onclick`) even though luci.d.ts only
+  declares `onclick` — follow the existing `click:` convention. Extend
+  `luci.d.ts` when you need a new LuCI global.
+
+## i18n
+
+- Wrap user-facing strings in `_()`, and only STRING LITERALS — the gettext
+  extractor (`yarn locales:actualize`) only sees literal args. Some validator
+  messages (vless/trojan) are currently NOT wrapped — wrap new ones.
+- i18n pipeline (`yarn locales:actualize` = extract-calls → generate-pot →
+  generate-po:ru → distribute). `extract-calls.js` scans BOTH `src/**/*.ts` AND
+  the hand-written `luci-app-netshift/.../view/netshift/**/*.js` (excludes
+  `main.js`), so `_()` strings added in `section.js` ARE extracted. Source of
+  truth for ru text is `fe-app-netshift/locales/netshift.ru.po` — fill the new
+  empty `msgstr` there (preserves existing translations on regen), then re-run
+  `yarn locales:distribute` to copy into the generated catalogs
+  `luci-app-netshift/po/{templates/netshift.pot, ru/netshift.po}`. Touched
+  catalog files: `locales/calls.json`, `locales/netshift.pot`,
+  `locales/netshift.ru.po`, `po/templates/netshift.pot`, `po/ru/netshift.po`.
+- TYPE-ONLY changes to `src/**` (e.g. adding interface fields in `types.ts`,
+  inside the `NetShift` namespace) erase at build → `main.js` has NO diff after
+  `yarn build`. Expect a clean `git diff` on `main.js` for pure-type edits.
+- `section.js` is a hand-written LuCI view, NOT bundled — `yarn format` only
+  touches `src/`, so format leaves section.js alone; keep its existing
+  2-space/double-quote style manually.
+
+## Version placeholder
+
+- `constants.ts` `NETSHIFT_LUCI_APP_VERSION='__COMPILED_VERSION_VARIABLE__'` is
+  substituted at OpenWRT build by `luci-app-netshift/Makefile` sed. In dev,
+  `normalizeCompiledVersion` turns anything containing `COMPILED` into `'dev'`.
+  Don't change the literal without updating the Makefile sed.
+
+## Tests
+
+- vitest `.test.js` files next to code under `tests/`, table-driven
+  `describe.each`, `_()` identity-mocked in `tests/setup/global-mocks.ts`, node
+  env (no DOM). New pure logic SHOULD ship a test. DOM/service/render code is
+  untested (no DOM mocks) — verify those by reasoning + build.
+- DO NOT import a `.test.js` from `methods/shell/index.ts` (or anything that
+  transitively imports the helpers barrel → `withTimeout` → `../netshift`
+  logger → `TabService` which calls `new MutationObserver` at module init).
+  In the node env that throws `MutationObserver is not defined` at COLLECT time
+  (suite fails with "no tests"). Fix: put pure/testable logic in its OWN module
+  that imports leaf helpers by DIRECT path (e.g. `../../../helpers/sleep`, NOT
+  the barrel), and import the test from that module. Done for task-008's
+  `pollSingBoxComponentAction.ts`.
+
+## Async core switch (task-008) — the rpcd 30s pattern
+
+- The core switch (sing-box install_extended/install_stable) must use the
+  ASYNC backend contract, not a single sync `component_action` exec — rpcd
+  kills any single fs.exec at 30s SERVER-SIDE regardless of the JS
+  `timeout:600000`. Pattern: `executeShellCommand(['component_action_async',
+  'sing_box', action])` → parse `{success,job_id,message}` → if no job_id,
+  fail fast → poll `['component_action_status', jobId]` in a loop every ~2s
+  with SHORT individual execs until `running !== true`; safety cap ~150 polls.
+  Each status call is tiny (ms) so never hits the wall.
+- Status contract fields (task-007/009): `{success,running,component,action,
+  message,pid,started_at,updated_at,exit_code,version,latest_version}`.
+  Map terminal → `{success, version, message}`.
+- `check_update` stays on the SYNC `component_action` path (fast, not subject
+  to 30s) — branch inside `singBoxComponentAction` on `action`.
+- Make the poll loop a PURE fn `pollSingBoxComponentAction(fetchStatus,
+  sleepFn=sleep, intervalMs, maxPolls)` with injected `fetchStatus`+`sleepFn`
+  so tests pass a no-op sleep (`() => Promise.resolve()`) and never wait 2s.
+  `sleep(ms)` lives in `helpers/sleep.ts` (Promise+setTimeout).
+- `showToast` type is only `'success' | 'error'` — for an in-progress info
+  toast just use `'success'` (don't widen the helper signature for it).
+- BARREL LEAK GOTCHA: adding `export * from './sleep'` to `helpers/index.ts`
+  made `sleep` appear as `main.sleep` in the generated baseclass.extend export
+  block (used barrel exports are NOT tree-shaken). For a truly INTERNAL helper,
+  do NOT put it in the barrel — place it next to its only consumer (e.g.
+  `methods/shell/sleep.ts`) and import by direct relative path. Verify after
+  build: `git diff main.js | grep '^\+\s\+[a-z]\+,$'` shows no new bare export
+  line. (task-008 M1.)
+- TESTING the REAL `singBoxComponentAction` despite the DOM/MutationObserver
+  collect crash: `vi.mock('<barrel path>', () => ({ executeShellCommand: ... }))`
+  short-circuits the `helpers`→`withTimeout`→`../netshift`→TabService chain so
+  the method module imports cleanly, THEN `const { X } = await import('../index')`.
+  CRITICAL: `vi.mock` factory paths are relative to the TEST file, and must
+  resolve to the SAME absolute module the SUT imports. From
+  `methods/shell/tests/`, the SUT's `../../../helpers` is `../../../../helpers`
+  from the test, and `./callBaseMethod` is `../../callBaseMethod`. Get these
+  wrong and the real (DOM-crashing) module loads → "MutationObserver is not
+  defined" at collect. (task-008 M2.)
+
+## Landmines
+
+- `runFakeIPCheck` allGood/atLeastOneGood logic looks inverted vs other checks —
+  don't "fix" without understanding intent.
+- Filename typo `checks/contstants.ts` is imported with the typo everywhere —
+  don't "correct" it and break imports.
+
+## Validator-test node globals (task-006)
+
+- `.test.js` files are linted as plain JS (typescript parser, no
+  `languageOptions.globals` in `eslint.config.js`), so bare `Buffer` / `btoa`
+  trips `no-undef` even though vitest runs in the node env at runtime. The
+  validator `.ts` files DON'T hit this (TS lib types cover `atob`). Fix in tests
+  WITHOUT editing eslint config: alias the node global via
+  `const NodeBuffer = globalThis.Buffer;` (`globalThis` is an allowed global) and
+  use `NodeBuffer.from(...).toString('base64')` for fixtures.
+- VMess `vmess://` is base64(JSON) (V2RayN), NOT user@host. `validateVmessUrl`
+  decodes with `atob` (right-pad to %4 with `=` for unpadded tolerance, matching
+  backend), JSON.parse, then narrows `Record<string, unknown>` for
+  `add`/`id`/`port`. It is dispatcher-only (NOT in `validators/index.ts`), exactly
+  like `validateHysteria2Url`. Craft a `+`-containing base64 fixture with a field
+  like `ps:'>>>'` (verified to force `+`).
+
+## Corepack yarn 4.x vs classic lockfile (task-006)
+
+- This repo's `yarn.lock` is v1 (classic) but corepack may activate yarn 4.16.0.
+  Running `yarn install` migrates the lockfile + creates `.yarn/`/`.yarnrc.yml`.
+  AVOID `yarn install`; node_modules is committed/present. Run CI steps via local
+  bins: `node_modules/.bin/{prettier --write src, eslint src --ext .ts,.tsx
+  --max-warnings=0, vitest run, tsup src/main.ts}`. Run locales via
+  `node {extract-calls,generate-pot,generate-po ru,distribute-locales}.js`.
+  Before reporting: confirm `git diff --exit-code -- fe-app-netshift/yarn.lock`
+  and no `.yarn`/`.yarnrc.yml`.
+- `locales/calls.json` is committed WITH Windows backslash paths
+  (`src\\validators\\...`) — generating it on Windows does NOT churn separators.
+- The proxy-link help string `"vless://, ... links"` is duplicated 3× in
+  `section.js` (proxy_string + selector + urltest fields) — use edit replaceAll.
+
+## VMess `#fragment` strip (task-012)
+
+- `vmess://<base64(JSON)>#name` — the `#…` is the server display-name remark
+  (same as vless/ss/trojan), but for VMess the name also lives in JSON `ps`.
+  V2RayN base64 NEVER contains `#`, so cut at the FIRST `#` before decode.
+- `validateVmessUrl` order MATTERS: derive `body = url.slice('vmess://'.length)`
+  → `b64 = body.split('#')[0]` → THEN run the `/\s/` whitespace check on `b64`
+  (NOT the full url), THEN pad/`atob` `b64`. This lets a `#name with spaces`
+  fragment validate while still rejecting whitespace inside the base64 body.
+  (The old code ran `/\s/` on the full url and padded `body` incl. fragment →
+  emoji/Cyrillic in `#🇳🇱Ne` corrupted base64 → "malformed base64".)
+- Real-user regression fixture is the long `eyJ…In0=#🇳🇱Ne` literal in the test;
+  keep a malformed-base64 negative case WITHOUT a `#` (`vmess://@@@@`) so it
+  still fails for the right reason, and a `vmess://<b64> ` (trailing space, no
+  `#`) case proving base64-body whitespace is still rejected.
+- main.js diff for this fix is exactly the `validateVmessUrl` function body
+  (body/b64 split + whitespace-on-b64 + pad b64) — expected-only.
+
+## settings.js section-picker pattern + DNS-via-outbound (task-015)
+
+- `settings.js` is a HAND-WRITTEN LuCI view (NOT bundled by tsup → editing it
+  yields NO main.js diff). The reusable "pick a proxy/vpn section" dropdown
+  pattern: `form.ListValue` + `o.depends(<flag>,'1')` + `o.cfgvalue` reading
+  `uci.get('netshift',section_id,<opt>)` + custom `o.load` that walks
+  `this.map?.data?.state?.values?.netshift ?? {}`, pushes secName to
+  `this.keylist`/`this.vallist` when `sec['.type']==='section'` AND
+  `connection_type` is NOT `block`/`exclusion`, returns `Promise.resolve()`.
+  Mirrors `download_lists_via_proxy_section` (settings.js ~294-321).
+- `dns_outbound_section` uses `rmempty=true` (empty = backend falls back to
+  first outbound) — intentionally differs from the download-proxy clone's
+  `rmempty=false`. Don't "normalize" it.
+- R3 trap: the spec called the diagnostic field "type-only ⇒ no main.js diff",
+  but adding the field to `types.ts` is type-only (erased at build) WHILE the
+  paired `runDnsCheck.ts` `insertIf` render IS RUNTIME CODE → it DOES produce a
+  legit main.js diff (the 10-line insertIf block). That regenerated main.js is
+  the deliverable; a second build is idempotent (no further diff). "No diff"
+  only holds if you skip the runDnsCheck.ts edit.
+- locales: ran `node {extract-calls,generate-pot,generate-po ru,
+  distribute-locales}.js` (NOT yarn → no corepack). New ru text goes in the
+  SOURCE `locales/netshift.ru.po` empty `msgstr`, then `distribute-locales.js`
+  copies to `po/ru/netshift.po` + `po/templates/netshift.pot`. Regen touches
+  calls.json/pot broadly (line-ref reshuffle + POT-Creation-Date header) but is
+  PURELY ADDITIVE — verified at msgid level: 5 added, 0 removed.
+- ENCODING TRAP (Windows/PS5.1): `git show HEAD:file > tmp` re-encodes the blob
+  to UTF-16 and MANGLES UTF-8 (emoji/Cyrillic) — gives FALSE "removed/added"
+  noise. Use `cmd /c "git ... > %TEMP%\f"` (preserves raw bytes) OR compare via
+  `git diff` directly. The committed .pot/.po ARE valid UTF-8; don't panic.
+- Console prints po/pot Cyrillic as mojibake — that's PS display only; verify
+  on-disk via `node -e "require('./locales/calls.json')...includes(...)"` or
+  UTF-8 byte reads, not the terminal.
+- New i18n keys (task-015) + ru: "Route main DNS through proxy/VPN"→"Основной
+  DNS через прокси/VPN"; "DNS outbound section"→"Секция outbound для DNS";
+  "Main DNS via outbound"→"Основной DNS через outbound"; long descriptions
+  translated equivalently.
+
+## validateIPV6 rewrite + concat-_() i18n (task-015 PR#11 fixes)
+
+- The OLD `validateIPV6` (two loose regexes + `colons>=2&&<=7` guard) WRONGLY
+  accepted `:::`, `1:2:::3`, `1::2::3` (multiple `::`), `1:2:3:4:5:6:7`
+  (incomplete 7-group). Replaced with a small functional checker (no `any`):
+  count `::` via `stripped.split('::').length-1` (reject >1); split into
+  head/tail, `countGroups(side)` splits on `:` and validates each as
+  `/^[0-9a-fA-F]{1,4}$/` hextet; group-count rule = exactly 8 when no `::`,
+  ≤7 when one `::` (it stands for ≥1 zero group). `''` side → 0 groups (so `::`
+  unspecified and `::1` work). Helpers `isHextet`/`countGroups`/`isEmbeddedIPv4`
+  are module-private (NOT in barrel) → no `main.*` export leak; verified diff
+  has no new bare export lines.
+- F-04 DECISION: ACCEPT IPv4-embedded IPv6 (`::ffff:192.168.1.1`,
+  `2001:db8::192.168.1.1`) — valid per RFC 4291. `countGroups` treats a LAST
+  group containing `.` as an embedded IPv4 (validated via `validateIPV4`) that
+  occupies TWO 16-bit groups (so it adds +1 to the group count). Tested both
+  positive and the malformed negatives.
+- main.js diff for this is EXACTLY the validateIPV6 function body + 3 private
+  helpers (52+/7- lines); second build idempotent. Expected runtime-code diff.
+- I18N CONCAT GOTCHA (F-02): `_('foo ' + 'bar')` is NOT extracted (gettext sees
+  only literal args; the `+` makes it an expression). The established repo
+  convention (see section.js community_lists ~415) is
+  `_('foo') + ' ' + _('bar')` — the SPACE lives OUTSIDE `_()`, and each literal
+  has NO trailing/leading space. `extract-calls.js` line 55 does `arg.value.trim()`
+  so a trailing space INSIDE `_('foo ')` is trimmed in the catalog → runtime
+  lookup of `'foo '` MISSES. So ALWAYS put separators outside `_()`. Fixed
+  global_proxy (section.js ~310), block_doh + enable_ipv6 (settings.js ~463/481).
+- locales regen: ran `node {extract-calls,generate-pot,generate-po ru,
+  distribute-locales}.js` (NOT yarn). `generate-pot.js` calls
+  `git config user.name`/`user.email` and CRASHES if unset → set them locally
+  (`git config --local user.name "..."`, email may be empty string which returns
+  rc=0). POT header churns (POT-Creation-Date timezone + `<>` from empty email)
+  — cosmetic, accepted; msgid-level diff was PURELY ADDITIVE (10 added, 0
+  removed). 10 new ru msgstrs filled in SOURCE locales/netshift.ru.po then
+  distributed to po/ru + po/templates (both end up byte-identical to source).
+- The 10 new ru fragments are the split sentences of the 3 flag descriptions
+  (global proxy / block DoH / enable IPv6) — translated formally/technically
+  matching neighbours. All catalogs LF, no empty non-header msgstr remained.
+
+## Component Manager tab (task-018)
+
+- NEW TAB = 5-file pattern mirroring `tabs/diagnostic`: `manager/{index,render,
+  initController,styles}.ts` + a hand-written `view/netshift/manager.js`
+  (`form.DummyValue _mount_node`, `o.rawhtml=true`, `cfgvalue` →
+  `main.ManagerTab.initController()` + `return main.ManagerTab.render()`).
+  Register in `netshift.js`: add `"require view.netshift.manager as manager"`
+  + a `form.TypedSection` block (`anonymous=true`, `addremove=false`,
+  `cfgsections=()=>["manager"]`). NB the tab UCI section name (`manager`,
+  `diagnostic`, `dashboard`) need NOT exist in `/etc/config/netshift` — LuCI
+  renders the virtual TypedSection anyway (diagnostic/dashboard prove it).
+- Barrel: add `export * from './manager';` to `tabs/index.ts` → `ManagerTab`
+  reaches `main.ManagerTab` (verified in the export block at the bottom of
+  main.js). Wire `ManagerTab.styles` into `src/styles.ts` `GlobalStyles` next to
+  Dashboard/Diagnostic. Styles use theme vars WITH fallbacks; CBI selector is
+  `#cbi-netshift-manager-_mount_node > div` + hide `#cbi-netshift-manager > h3`.
+- LIFECYCLE: mirror diagnostic exactly but guard re-init with module-level
+  `*Registered`/`*Initialized`/`*Mounted` booleans since the
+  lazy-mount listener can fire repeatedly. `onMount('manager-status')` →
+  `registerLifecycleListeners()` (subscribe on `tabService.current==='manager'`)
+  → `onPageMount` subscribes store + renders + fetches systemInfo;
+  `onPageUnmount` resets `['managerActions','managerChecks']`.
+- INSTALLED-NOW / LATEST-ON-DEMAND: installed versions come from
+  `diagnosticsSystemInfo` (reuse the diagnostic `getSystemInfo()`→store slice);
+  latest is fetched ONLY on a "Check update" click. Pure card builder
+  `cards.ts:getComponentCards(systemInfo, checks)` + `getCheckTag(status)` +
+  `isSingBoxInstalled` are DOM/store-free (import only `normalizeCompiledVersion`
+  leaf + `NetShift` types) → unit-testable WITHOUT the MutationObserver collect
+  crash. Controller maps descriptors→DOM+click handlers. 3 cards: netshift,
+  sing_box_stock, sing_box_extended; inactive core → "Not installed" + switch.
+- BACKEND CONTRACT (task-017, STABLE): both SING-BOX checks (`check_update`
+  extended / `check_update_stable` stock) return `{success,current_version,
+  latest_version,status:"latest"|"outdated"|"dev"|"not_installed"}`. The
+  PRE-EXISTING `singBoxComponentAction('check_update')` only parsed `{success,
+  version,message}` (DROPPED status/latest) — do NOT route the manager check
+  through it. Added ONE `singBoxCheckUpdate(action)` method parsing the FULL
+  contract via a pure `parseComponentCheckUpdate.ts` (types-only import, status
+  whitelisted). Install/switch reuse the existing async
+  `singBoxComponentAction('install_*')` + `pollSingBoxComponentAction`.
+- C1 (review fix) — THERE IS NO `netshift:check_update` BACKEND ACTION. NetShift
+  latest comes ONLY from `get_system_info.netshift_latest_version`. So the
+  NetShift card's "Check update" must NOT route through `singBoxCheckUpdate` (that
+  would run the sing-box EXTENDED check and write its status into
+  `managerChecks.netshift` → wrong). Fix: give the NetShift check a DISTINCT
+  `kind:'check_netshift'` (no `backendAction`) so `handleManagerAction` routes it
+  to `runNetshiftCheck`, which RE-FETCHES systemInfo + `resetCheckResult
+  ('netshift')` and derives the badge/toast from installed-vs-latest. NetShift
+  status is derived PURELY from systemInfo (`netshiftStatus(systemInfo)` no longer
+  reads `managerChecks.netshift`). Regression guards in cards.test.js: NetShift
+  action kind is `check_netshift`, has NO `backendAction`, and status ignores a
+  bogus `managerChecks.netshift`. LESSON: when a card's "latest" comes from a
+  DIFFERENT source than its siblings, give it its own action kind so the shared
+  dispatcher can't misroute it to the wrong backend method.
+- S1 (review fix) — keep ONE check method per concern: removed the dead
+  `singBoxCheckUpdateStable()` (0 callers; controller uses
+  `singBoxCheckUpdate('check_update_stable')`). No dead exports.
+- M2 (review fix) — `ManagerComponentKey` defined ONCE in `tabs/manager/cards.ts`
+  (the pure module) and `export type`-re-exported from `store.service.ts` (which
+  `import type`s it) so store consumers keep their path; safe because cards.ts
+  imports NO store (no cycle). M1 (self-update timeout reusing 'Core switch
+  timed out' wording) left as-is — non-blocking, and the shared
+  `pollSingBoxComponentAction` wording is approved for the core-switch path.
+- SELF-UPDATE lenient polling: `netshiftSelfUpdate()` starts
+  `component_action_async netshift self_update`; once a `job_id` is returned, the
+  poll `fetchStatus` callback SWALLOWS exec/parse errors and returns a synthetic
+  `{running:true}` (instead of `null`, which the pure poll treats as terminal
+  failure). This prevents the mid-job `/usr/bin/netshift` binary swap from
+  misreporting success as failure; `MAX_POLLS` still bounds it. On success: a
+  warning-style toast then `window.location.reload()` after 1200ms.
+- MOVED core-switch OUT of Diagnostics: removed `handleInstallSingBox` +
+  `singBoxInstall`/`singBoxExtended` from `diagnostic/initController.ts` and the
+  `singBoxInstall` block + props from `renderAvailableActions.ts`, and the
+  `singBoxInstall` slice from BOTH `StoreType` and `diagnostic.store.ts`. Net
+  i18n effect: msgids "Install stable"/"Install extended" were DROPPED (now-dead)
+  and replaced by manager's "Switch to stable"/"Switch to extended"/"Install %s"
+  — so the ru.po diff is NOT purely additive this time (2 removed, ~16 added);
+  that is correct. `renderRotateCcwIcon24` stays imported (still used by Restart).
+- i18n: 16 new ru msgstrs filled in SOURCE `locales/netshift.ru.po`, then
+  `node distribute-locales.js`. "%s" placeholder strings ("Install %s") are
+  single literals (no concat); progress/result toasts concatenate the version
+  OUTSIDE `_()` (`` `${_('NetShift updated, version:')} ${v}` ``). Ran the
+  locales scripts via `node {extract-calls,generate-pot,generate-po ru,
+  distribute-locales}.js`. yarn here was classic 1.22.22 (NOT corepack) so
+  `yarn ci` was safe — verified yarn.lock unchanged + no `.yarn/.yarnrc.yml`.
+- main.js: +756/-… runtime diff (new tab + methods + core-switch removal),
+  second build idempotent (byte-identical), banner + `return baseclass.extend`
+  intact, only `ManagerTab` added to the export block (pure helpers imported by
+  direct path → no leak). `tsc --noEmit` flags ONE pre-existing error in
+  `getNetshiftVersionRow.test.ts` (sing_box_extended optionality) — NOT in CI
+  (yarn ci = format/lint/vitest/build, no tsc), pre-existing, ignore.
+
+## Drop stale nft "mangle output counters" check (task-020b)
+
+- Backend 020a removed `rules_mangle_output_counters` from `check_nft` JSON
+  (router-output traffic is intentionally DIRECT now → that chain's counter is
+  legitimately 0, so the non-zero assertion was a FALSE positive). New STABLE
+  7-key shape: `{table_exist, rules_mangle_exist, rules_mangle_counters,
+  rules_mangle_output_exist, rules_proxy_exist, rules_proxy_counters,
+  rules_other_mark_exist}` — `rules_mangle_output_exist` KEPT.
+- FE removal touched exactly 2 source files: `runNftCheck.ts` (drop the field
+  from the allGood `&&` chain, the atLeastOneGood `||` chain, and its `items[]`
+  row — keep the "Rules mangle output exist" row) + `types.ts`
+  `NftRulesCheckResult` (drop `rules_mangle_output_counters: 0 | 1;`).
+- main.js: runtime diff is the removed Boolean()s + the dropped items[] row;
+  second build BYTE-IDENTICAL (idempotent), banner + `return baseclass.extend`
+  intact; `grep -c rules_mangle_output_counters main.js` == 0.
+- locales: ran `node {extract-calls,generate-pot,generate-po ru,
+  distribute-locales}.js` (NOT yarn → no corepack). The unused
+  `_('Rules mangle output counters')` msgid dropped cleanly from ALL 5 catalogs
+  (calls.json, locales/netshift.{pot,ru.po}, po/{templates/netshift.pot,
+  ru/netshift.po}). msgid-level delta = PURELY a removal (1 removed, 0 added);
+  "Rules mangle output exist" stays. generate-po reported 325/323 (2 stale
+  translations retained in source ru.po — harmless, additive-preserving).
+- yarn was classic 1.22.22 → `yarn ci` safe; verified `git diff --exit-code --
+  yarn.lock` clean and NO `.yarn`/`.yarnrc.yml`. No vitest referenced the field.
+
+## validateUrl accepts IP host + subscription_insecure checkbox (task-021a)
+
+- `validateUrl.ts` REWRITE: old regex required an ALPHA TLD so an IPv4/IPv6 host
+  was rejected ("Invalid URL format"). New approach mirrors `validateSocksUrl`:
+  keep the protocol check (default `['http:','https:']`), then a pure
+  module-private `extractHost(url)` strips `scheme://` (indexOf '://'), the
+  `/path?query#frag` (`rest.search(/[/?#]/)` — first of `/ ? #`), optional
+  `userinfo@` (`lastIndexOf('@')`), and the `:port`. BRACKETED IPv6:
+  if `rest.startsWith('[')`, return the substring between `[` and the first `]`
+  (so `[2001:db8::1]:2096` → `2001:db8::1`); else strip trailing `:port` via
+  `lastIndexOf(':')`. Then accept if `validateIPV4(host).valid ||
+  validateIPV6(host).valid || validateDomain(host).valid`. Kept the 3 existing
+  messages verbatim (`Invalid URL format`, the protocol message, `Valid`).
+- NB `validateIPV6` ALREADY unwraps brackets internally (`.replace(/^\[/,'')`),
+  but extractHost must unwrap anyway so the `:port` after `]` is dropped before
+  the validator sees it. `extractHost` is NOT barrel-exported (module-private) →
+  no `main.*` leak; main.js diff is +30/-4 (the helper + the host-check), second
+  build BYTE-IDENTICAL, banner + `return baseclass.extend({` intact.
+- This single fix covers ALL FOUR callers (subscription_url, urltest_testing_url,
+  remote_domain_lists, remote_subnet_lists) — callers unchanged.
+- TESTS: `validateDomain` accepts a trailing path (`example.com/path` regex has
+  `(?:\/[^\s]*)?$`), so existing domain-with-path valid cases still pass through
+  the domain branch. Added valid: `https://91.199.111.52:2096/sub/abc`,
+  `http://10.0.0.1/x`, `https://[2001:db8::1]:2096/sub`. Added invalid:
+  `https://999.1.1.1/x` (bad IPv4 → not domain either), `ftp://1.2.3.4` (protocol
+  fails first), `https://` (extractHost → '' → "Invalid URL format"). Kept
+  `https://google` invalid (no TLD, not an IP).
+- section.js (HAND-WRITTEN, NOT bundled → 0 in main.js): added `form.Flag`
+  `subscription_insecure` right AFTER subscription_url (~line 113), default `"0"`,
+  `rmempty=false`, `depends({connection_type:'proxy',proxy_config_type:
+  'subscription'})` exactly like its siblings (no `subscription_user_agent` exists
+  here despite the spec mention). Multi-sentence description = three `_()` calls
+  joined with `+ " " +` OUTSIDE `_()` (F-02 rule). UCI contract option name
+  `subscription_insecure` (0|1) consumed by backend 021b.
+- locales: `node {extract-calls,generate-pot,generate-po ru,distribute-locales}.js`
+  (NOT yarn). 4 new msgids (1 label + 3 description sentences), PURELY additive
+  (4 added, 0 removed at msgid level). Filled RU in SOURCE `locales/netshift.ru.po`
+  then distributed → po/ru + po/templates byte-identical to source. Only the PO
+  HEADER msgstr stays empty (`grep -nB1 'msgstr ""'` shows just line 6/7).
+- yarn classic 1.22.22 → `yarn ci` green (format/lint --max-warnings=0/471 tests/
+  build); verified yarn.lock unchanged + NO `.yarn`/`.yarnrc.yml`. The
+  `netshift/files/**` + `tests/**` changes in git status are 021b (other agent),
+  not mine.

docs/agent-rules/memory/packaging-ci-engineer.md

@@ -0,0 +1,107 @@
+# Memory — packaging-ci-engineer
+
+Durable packaging / CI / release knowledge. Read before working; append
+findings; keep under ~200 lines.
+
+## Packages
+
+- `netshift` (backend) and `luci-app-netshift` (UI; also yields
+  `luci-i18n-netshift-ru` via `LUCI_LANGUAGES=en ru`). Both `PKGARCH=all`.
+- `netshift/Makefile`: DEPENDS `+sing-box +curl +jq +kmod-nft-tproxy
+  +coreutils-base64 +bind-dig`; CONFLICTS `https-dns-proxy nextdns
+  luci-app-passwall luci-app-passwall2`; version
+  `PKG_VERSION = $(if $(NETSHIFT_VERSION),$(NETSHIFT_VERSION),0.$(date +%d%m%Y))`;
+  `prerm` removes `105 netshift` from `/etc/iproute2/rt_tables` and stops the
+  service; conffile `/etc/config/netshift`; stamps
+  `__COMPILED_VERSION_VARIABLE__` into `constants.sh` via sed (NO `|| true`, so a
+  missing file fails the build).
+- `luci-app-netshift/Makefile`: uses `luci.mk`, `LUCI_DEPENDS=+luci-base
+  +netshift`; stamps the same placeholder into `main.js` (WITH `|| true`, so a
+  missing main.js silently won't stamp). Asymmetric on purpose — note it.
+
+## Docker build images
+
+- `Dockerfile-ipk` FROM `itdoginfo/openwrt-sdk-ipk:24.10.6`;
+  `Dockerfile-apk` FROM `itdoginfo/openwrt-sdk-apk:25.12.3`.
+- KNOWN INCONSISTENCY (intentional, do NOT "fix" blindly): ipk Dockerfile
+  exports `NETSHIFT_VERSION="v${NETSHIFT_VERSION}"` (adds a `v`); apk sets it
+  raw (no `v`). Embedded version vs artifact filenames can differ across types.
+- `sdk/Dockerfile-sdk-*` are the base SDK images (feeds update + luci-base);
+  apk SDK requires running `./setup.sh` first.
+
+## Release flow (build.yml, on tag push)
+
+smoke-tests gate -> `preparation` derives version (`git describe --tags
+--exact-match`, fallback `0.<date>`) -> matrix build ipk+apk -> `docker cp`
+artifacts out of the container -> **ipk underscore->dash rename**
+(`sed 's/_/-/g'`) -> filter to the 3 packages -> GitHub Release.
+
+- The underscore->dash rename is LOAD-BEARING: `install.sh` scrapes the
+  latest-release API and matches assets by package-name prefix
+  (`netshift*`, `luci-app-netshift*`, `luci-i18n-netshift-ru*`). Breaking the
+  rename breaks install.
+
+## Smoke tests (tests/)
+
+- Image = OpenWRT 24.10.6 rootfs; source is **bind-mounted at runtime**
+  (`../netshift/files -> /netshift/files:ro`), so editing `netshift/files` is
+  picked up without rebuilding the image.
+- Needs `NET_ADMIN`/`NET_RAW`/`SYS_ADMIN` + `network_mode: host` for nft/dns;
+  nft tests FAIL (not skip) without caps.
+- `all` runs: deps syntax config helpers jq cm sb nft diagnostics subscription.
+- Add a test: `test_xyz()` (header/pass/fail/skip), add to `main()` `all)` list,
+  add `case` alias, update usage line + docker-compose comment. Keep the two
+  compose invocations (build.yml smoke vs openwrt-smoke-tests.yml) in sync.
+- Smoke baselines drift as tests get added: 81 passed (pre task-016) -> 84
+  passed after adding `test_nft_ipv6` (3 v6 assertions). Re-confirm the baseline
+  from the actual run, don't trust a stale number in a task spec.
+- `test_nft_ipv6` (alias `nftv6`, task-016): real-nft regression guard for the
+  B-01 IPv6 tproxy blocker. Builds the v6 tproxy rule from constants
+  (`SB_TPROXY_INBOUND_ADDRESS_V6`/`_PORT_V6`) in a throwaway `inet` table, lists
+  it back, and asserts it normalizes to bracketed `[::1]:1603` (positive) and
+  that no portless bare form (`tproxy ip6 to ::0`) appears (negative guard). The
+  unbracketed bug (`::1:1603`) is normalized by nft to a portless bare addr
+  (`[::1:1603]` / `[::0.1.22.3]` depending on nft version) — either way the
+  `\[::1\]:1603` grep fails, so the guard fires. Capability-gated: an
+  ip6-tproxy "not supported"/"operation not supported" kernel `skip`s; a
+  successful-but-wrong load `fail`s. SELF-PROVEN: temp scratch with unbracketed
+  rule -> 1 failed (guard caught it), reverted.
+- Smoke test capability gating pattern: capture `add_err="$(nft add ... 2>&1)"`
+  inside the `if`; on success run asserts, on failure `case "$add_err"` for
+  *not supported* substrings -> `skip`, else `fail`. Avoids false-fails on
+  kernels lacking a feature while still catching real bugs.
+- jq `index()` truthiness nit: `index("x") and index("y")` works (jq treats 0 as
+  truthy) but prefer `(index("x") != null) and (index("y") != null)` for intent
+  + 0-index robustness. Was at entrypoint.sh:688.
+- WSL2 kernel (6.6.x-microsoft-standard-WSL2) DOES support ip6 tproxy in the
+  smoke container, so the v6 assertions run (not skip) locally.
+- nft v6 buggy-form normalization is VERSION-DEPENDENT: the PROOF doc saw
+  `[::0.1.22.3]` (nftables v1.1.3), but the OpenWRT 24.10.6 smoke container
+  re-prints unbracketed `::1:1603` as `[::1:1603]` (no `]:` port sep). A
+  negative guard that greps a single literal (`\[::0`) is therefore a DEAD
+  assertion on the smoke env. ROBUST pattern: flag any `tproxy ip6 to [...]`
+  line that is NOT the correct `[::1]:1603` ->
+  `grep 'tproxy ip6 to \[' | grep -qv '\[::1\]:1603'`. Catches both
+  normalizations + future variants. Self-proved: unbracketed scratch -> BOTH
+  positive (`bracketed`) and negative (`no-bare`) guards FAIL (2 failed).
+
+## CI gates by path
+
+- `frontend-ci.yml`: PRs touching `fe-app-netshift/**` -> yarn install /
+  format(diff) / lint(--max-warnings=0) / test / build(diff).
+- `shellcheck.yml`: `install.sh` + `usr/bin/netshift` + `usr/lib/**.sh`,
+  severity error (Differential ShellCheck).
+- `openwrt-smoke-tests.yml`: `netshift/**`, `luci-app-netshift/**`, `tests/**`,
+  `install.sh`, Dockerfiles -> entrypoint `all`.
+- `.gitlab-ci.yml` declares a `test` stage but runs no tests — only builds and
+  deploys Docker on master. Quality is enforced by the AI review workflow + the
+  GitHub Actions above, not GitLab.
+
+## install.sh
+
+- POSIX; apk/opkg abstraction; podkop->netshift migration STOPS the old service
+  first (that restores dnsmasq keys + removes PodkopTable + `105 podkop`),
+  backs up config to `/etc/config/podkop.bak.pre-netshift`. OpenWRT 23.05
+  unsupported; needs >=15 MB on `/overlay`; NO uninstall path (removal lives in
+  package `prerm`). GitHub API rate-limit is a known fragility (wget path has no
+  guard).

docs/agent-rules/memory/shell-backend-developer.md

@@ -0,0 +1,653 @@
+# Memory — shell-backend-developer
+
+Durable backend (ash + jq) knowledge. Read before implementing; append
+findings; keep under ~200 lines.
+
+## Hard constraints (proven)
+
+- **OpenWRT jq has NO Oniguruma** — `test()`, `match()`, `sub()`, `gsub()` and
+  any regex are unavailable. The updater (`updater.sh`) documents workarounds.
+  Build string logic with `split`/`startswith`/`endswith`/`contains`/`ascii`
+  instead.
+- **`fatal` is only a log label** — `log "..." "fatal"` does NOT exit. You must
+  follow it with `exit 1` yourself. Missing the `exit 1` continues with a
+  half-built config.
+- **busybox sed lacks `\x` escapes** — use printf-octal workarounds (see
+  `helpers.sh` `convert_crlf_to_lf` and BOM stripping). Don't assume GNU sed.
+- **Diagnostic strings are UTF-8, NOT mojibake** (corrected by task-004). The
+  emoji/box-drawing in `usr/bin/netshift` (`global_check`, `list_update`,
+  `subscription_update`, `check_nft`: `📡 🛠️ ✅ ❌ ⚠️ ➡️ 🧱 🥸 📄 ━`) are valid
+  UTF-8 and must STAY valid UTF-8. They were once double-encoded (UTF-8 read as
+  CP1251, re-saved as UTF-8 → printed `рџ…`/`в”…`/` `). Never open/save that file
+  in a non-UTF-8 editor or pass it through CP1251 — it re-corrupts. The earlier
+  "preserve the corrupted bytes" note here was the WRONG guidance that protected
+  the bug.
+
+## Conventions (follow exactly)
+
+- File header: `# shellcheck shell=ash`; constants files add
+  `# shellcheck disable=SC2034`. Declare every variable `local`.
+- Function prefixes: `sing_box_cm_*` = one jq mutation each (dumb primitive);
+  `sing_box_cf_*` = facade (parse + several cm_* calls); `url_*` = pure URL
+  parsing; `is_*` = predicate returning 0/1; `nft_*` = nft wrapper; `updates_*`
+  = updater; `get_*_tag` = deterministic tag builder; `configure_*`/`import_*`/
+  `_*_handler` = config_foreach callbacks; leading `_` = private helper.
+- Config threading: `$config` is a shell STRING; cm/cf take it as `$1`, echo
+  mutated JSON; caller does `config=$(sing_box_cm_... "$config" ...)`.
+- jq optional keys: `+ (if $x != "" then {k:$x} else {} end)`. Custom helpers
+  in `helpers.jq`, imported `import "helpers" as h {"search":"/usr/lib/netshift"}`.
+- Validation is mandatory: write to `*.tmp.$$`, run `sing-box -c <file> check`
+  (fatal on fail), `jq -e` for shape, md5sum-compare, then `mv`. Atomic only.
+- New constants -> `constants.sh` (grouped Common/nft/sing-box/Lists). Never
+  hardcode ports/IPs/marks/paths.
+- The service-tag pattern: cm_* functions stamp a transient `__service_tag`
+  (`SERVICE_TAG`) on rules; `sing_box_cm_save_config_to_file` strips every
+  `__service_tag` via `walk(...)` before writing. Don't leave tags in output.
+
+## Subscription / unavailable-outbound flow (don't leak traffic)
+
+- Many code paths branch on `subscription_outbound_is_unavailable` to emit
+  **reject** route rules instead of routes when a subscription is down. Any new
+  routing code MUST respect this or it leaks traffic when a sub is unavailable.
+
+## Testing
+
+- Smoke suite is `tests/entrypoint.sh` (run via `smoke-tests` skill). Categories:
+  deps syntax config helpers jq cm sb nft diagnostics subscription.
+- To add a test: write `test_xyz()` using the `header`/`pass`/`fail`/`skip`
+  helpers; add it to `main()`'s `all)` list; add a `case` alias; update the
+  usage line and the docker-compose comment. Config-gen and subscription
+  parsing changes SHOULD get a smoke test.
+- Pre-commit-equivalent: always run the `shellcheck` skill (severity error) on
+  touched shell files before handing back.
+
+## jq gotchas (proven by task-002)
+
+- **`include` / `exclude` are RESERVED jq keywords** — you cannot name a jq
+  variable `$include` (jq tries to parse the `include` directive). Use `$inc`/
+  `$exc` etc. for keyword-filter lists.
+- **`any(gen; cond)` / `all(gen; cond)` binding trap**: inside the condition,
+  `.` is the generator element ONLY at the top of `cond`. If you write
+  `($name | index(.))` the `.` becomes `$name` (the pipe rebinds `.`), so the
+  match silently always succeeds. Bind first: `any($kw[]; . as $k | ($name |
+  index($k)) != null)`.
+- Subscription keyword filter lives in `sing_box_cf_prepare_subscription_batch`
+  (facade), runs BEFORE static-unsupported filter + tag dedup, threaded from the
+  `subscription)` branch via two UCI **list** options
+  `subscription_filter_include_keywords` / `subscription_filter_exclude_keywords`
+  (the cross-layer contract names for task-003 — do NOT rename). Keywords are
+  opaque user text: collect with a `config_list_foreach` handler that jq
+  `--arg`-appends each item into a JSON array (commas/emoji survive; never use
+  `comma_string_to_json_array` for them). Empty result reuses the existing
+  `mark_subscription_outbound_unavailable` fail-safe (no `exit 1`).
+
+## Known landmines
+
+- nft proxy chain hardcodes `127.0.0.1:1602` (duplicates the constants).
+- VPN `domain_resolver` uses wrong variable `$dns_server`.
+- `check_nft` references stale set names (`netshift_domains`) / UCI options that
+  don't exist elsewhere — likely copied diagnostic cruft.
+
+## task-004: double-encode repair recipe (reusable)
+
+- To reverse a UTF-8→CP1251 double-encode losslessly: `text =
+  bytes.decode("utf-8"); fixed = text.encode("cp1251").decode("utf-8")` then
+  write `fixed.encode("utf-8")`. ASCII bytes pass through; verify 0
+  cp1251-unmappable chars and that ASCII-stripped lines are byte-identical
+  before/after (proves no code moved). Result was exactly 114 lines, all
+  non-ASCII-only. LF/no-BOM preserved.
+- On Windows here, `python3.exe` is the MS Store stub — use `python` (Python
+  3.11 at `...\Programs\Python\Python311`). Don't `print()` emoji to the
+  PowerShell console (cp1251 codepage mangles it / raises); write results to a
+  UTF-8 file and read it back.
+## task-005 review-001: vmess base64 + url_decode landmine (proven)
+
+- `sing_box_cf_add_proxy_outbound` runs `url=$(url_decode "$url")` BEFORE the
+  scheme `case`, and `url_decode` does `s/+/ /g`. Any scheme that base64-decodes
+  the WHOLE payload (vmess `vmess://base64(JSON)`; future tuic/etc.) MUST decode
+  from the RAW link, not the url_decode'd one — standard base64's alphabet
+  includes `+`, so `+`→space corrupts ~1-in-64 real keys. Fix pattern: capture
+  `local raw_url="$3"` at the top (before url_decode) and pass `$raw_url` to the
+  whole-payload decoder. Other scheme cases keep using the url_decode'd `$url`.
+- **busybox `tr` does NOT support POSIX char classes** — `tr -d '[:space:]'`
+  deletes the LITERAL chars `[ : s p a c e ]` (silently corrupts base64!). Use
+  explicit bytes: `tr -d ' \011\012\015'` (space/tab/LF/CR octal). Verified
+  in-container: input `aZ:[]cept123` → `Zt123` with `[:space:]`. This was a real
+  regression I introduced and caught via the `sb` smoke run.
+- base64 padding normalization for unpadded links: right-pad payload length to a
+  multiple of 4 with `=` using `pad=$(( ${#p} % 4 ))` then a `while` append loop.
+  POSIX-safe, busybox-safe.
+- To craft a base64 body that DELIBERATELY contains `+`: a `ps`/label value of
+  `node>>` (bytes 0x3E 0x3E) forces a 6-bit group = 62 → `+`. Realistic ASCII
+  host/word values rarely hit it; `>>` is reliable.
+- Probing helpers in-container without fighting PowerShell quoting: write a tiny
+  `.sh` into `netshift/files/usr/lib/` (it's bind-mounted into the smoke
+  container at `/netshift/files`), run via
+  `docker compose ... run --rm --entrypoint sh netshift-test /netshift/files/usr/lib/_tmp.sh`,
+  then delete it. Inline `-c "..."` one-liners get mangled by PowerShell.
+
+- `test_syntax` in `tests/entrypoint.sh` now also `ash -n`'s `usr/bin/netshift`
+  and asserts no residual `рџ`/`в”`/`вЂ` markers (built via `printf` octal, since
+  busybox grep lacks `\x`). Guards against re-introducing the mojibake.
+
+## task-007: async component-action job state (rpcd 30s wall fix)
+
+- Root cause of "core switch fails": the UI called `component_action sing_box
+  install_extended` SYNCHRONOUSLY via rpcd `fs.exec`; rpcd has `-t 30` and kills
+  the worker mid-extract (after `tar -O > /usr/bin/sing-box`, before
+  `chmod 0755`). The JS-side `timeout: 600000` does NOT help (server-side limit).
+  Fix = fork the worker detached; return a job_id in <<30s; poll status.
+- Job-state machinery lives in `updater.sh` (jq, no ucode). State dir `/var/run/netshift/
+  component-actions` (tmpfs). Constants: `UPDATES_JOB_DIR`,
+  `UPDATES_JOB_FINISHED_TTL_MINUTES=60`, `UPDATES_JOB_ORPHAN_OUTPUT_TTL_MINUTES=60`,
+  `UPDATES_JOB_STALE_GRACE_SECONDS=15`.
+- **State object contract (STABLE — frontend task-008 depends on these field
+  names):** `{ success, running, component, action, message, pid, started_at,
+  updated_at, exit_code, version, latest_version }`. running:
+  `running:true,success:true,exit_code:null`. finished: `running:false`,
+  success/version/message parsed from the worker stdout JSON, exit_code from `$?`.
+- HUP-proof fork: `( trap '' HUP; "$0" component_action "$c" "$a" >"$out" 2>&1;
+  updates_write_finished_job_state ... "$?" "$out" ) >/dev/null 2>&1 &`; record
+  `$!` into the running state via `updates_update_running_job_pid`. `trap '' HUP`
+  is what survives the rpcd session close. The async wrapper NEVER `exit 1`s on a
+  worker failure — the failure is recorded in the finished state.
+- finished-state stdout parser (`updates_extract_worker_json`): `updates_log`/
+  `echolog` can pollute the worker's stdout, so: (1) if the WHOLE file is valid
+  JSON (`jq -e .`) use it; else (2) `sed -n 's/^[^{]*\({.*\)$/\1/p' | tail -n 1`
+  then `jq -e` validate. sed is busybox-safe; NO Oniguruma. success derives from
+  `$w.success // ($exit_code == 0)`; version from `$w.version // $w.current_version`.
+- Path-traversal guard: `updates_job_state_path` rejects ids matching
+  `*[!A-Za-z0-9._-]*` or empty/`.`/`..` → return 1. The id comes straight from
+  the (ACL-gated) UI, so this is the security boundary. `component_action_status`
+  returns a safe self-contained `{success:false,running:false,...}` (via
+  `updates_job_status_response`, non-zero rc) for invalid id / missing file.
+- Stale detection (`updates_refresh_running_job_state`): running:true but pid not
+  `kill -0` alive AND past `started_at + STALE_GRACE` → rewrite as finished/stale
+  (`success:false`). Prevents the UI polling a crashed worker forever.
+- Idempotent install (Req 4): at the START of `updates_install_sing_box_extended`,
+  if `/usr/bin/sing-box` exists but is not `-x` OR fails a `version` probe, `rm`
+  it up front (don't back up a broken partial artifact). `chmod 0755` stays
+  IMMEDIATELY after stream-extract and BEFORE validation — keep that order.
+- **`set -e` + command substitution landmine (smoke harness):** under `set -e`,
+  `x="$(cmd-that-returns-nonzero)"` ABORTS the whole script. When a test
+  deliberately invokes a failing command (e.g. invalid-id status returns rc 1),
+  run it as `cmd > tmpfile 2>/dev/null || rc=$?` then read tmpfile — do NOT
+  capture via `$(...)` in an assignment, and do NOT use `|| true` (that clobbers
+  `$?` so you can't assert the non-zero rc). This cost me one debug cycle.
+- **Brace-in-default-param landmine (busybox ash):** `${VAR:-{json...}}` emits an
+  EXTRA literal `}` even when VAR is set (the inner `{...}` confuses the `}`
+  matching), corrupting JSON. Use `[ -z "$VAR" ] && VAR='{...}'` then print `$VAR`.
+- New top-level smoke test `test_jobstate` (alias `jobstate`): stubs the worker
+  via a tiny generated CLI whose `$0` IS the stub (because `component_action_async`
+  forks `"$0" component_action ...`); controls the worker with `STUB_JSON`/
+  `STUB_SLEEP`/`STUB_RC` env; isolates state under `JOBSTUB_DIR`. Registered in
+  `all)`, case alias, usage line, and the docker-compose comment.
+- Dispatcher (`bin/netshift`): `component_action_async) component_action_async
+  "$2" "$3" ;;` and `component_action_status) component_action_status "$2" ;;`
+  replaced the old naive `"$0" component_action ... > /tmp/...json &` hack. ACL
+  needs NO change (`/usr/bin/netshift` is exec-allowed wholesale).
+
+## task-009: core-switch connectivity self-heal + rollback (anti-brick)
+
+- Root cause of the on-hardware brick: `updates_install_sing_box_stable`
+  removed/replaced /usr/bin/sing-box via opkg/apk with NO backup, while the
+  kill-switch (nft tproxy + dnsmasq->127.0.0.42->dead sing-box) blocked feed
+  access. Binary GONE, no rollback. Extended path already had a tmpfs backup.
+- Fix shape (variant B): both install paths are now thin PUBLIC wrappers
+  (`updates_install_sing_box_extended`/`_stable`) that run
+  `updates_ensure_connectivity <dir>` (preflight; if fail -> selfheal) then call
+  the renamed private core (`_updates_install_sing_box_*_core`), then ALWAYS
+  `updates_restore_after_swap`. **Epilogue guarantee = single cleanup call**:
+  core echoes JSON to a `/tmp/...result.$$` capture file + returns rc; wrapper
+  runs restore once, re-emits the JSON, returns rc. No early return skips it (no
+  trap needed — the wrapper has exactly one core call).
+- `updates_preflight_connectivity <stable|extended>` is direction-aware: stable
+  probes `UPDATES_FEED_PROBE_HOST` (downloads.openwrt.org), extended probes
+  `UPDATES_GITHUB_PROBE_HOST` (api.github.com). Probe = DNS resolve (dig
+  `+short`, nslookup fallback; bind-dig is a dep) AND a curl `-fsSI`/wget
+  `--spider` HEAD with `--connect-timeout 5`. No jq/regex.
+- `updates_selfheal_connectivity`: (1) backup `/etc/resolv.conf` to tmpfs
+  (`UPDATES_RESOLV_BACKUP`), write temp resolver (`UPDATES_HEAL_RESOLVERS`
+  1.1.1.1+9.9.9.9) atomically, recheck; (2) if still failing, tear down redirect
+  via the EXISTING `/etc/init.d/netshift stop` (dnsmasq_restore + stop_main),
+  recheck. Records `UPDATES_HEAL_RESOLV_REPLACED`/`UPDATES_HEAL_REDIRECT_DOWN`
+  module-level flags so the epilogue restores EXACTLY what changed (restore
+  resolv.conf via mv-back, bring redirect up via `/etc/init.d/netshift start`).
+  Reused stop/start so dnsmasq UCI + shutdown_correctly bookkeeping stays right;
+  NO hand-rolled nft flush, NO sacred-constant change.
+- Stable core gained tmpfs backup/rollback (`updates_stable_rollback`) mirroring
+  the extended path: backup binary+libcronet BEFORE package install; restore on
+  install-fail OR still-extended validation. CRITICAL ordering: connectivity is
+  confirmed (preflight/heal in the wrapper) BEFORE the core touches the binary —
+  if heal fails the wrapper aborts and nothing is removed.
+- **Testability indirection**: added `UPDATES_SING_BOX_BIN`/`UPDATES_LIBCRONET_LIB`
+  constants (default the real /usr/bin/sing-box, /usr/lib/libcronet.so) and used
+  them in the STABLE core+rollback only, so the smoke test can point them at
+  /tmp mocks without clobbering the container's real binary. Extended path still
+  uses the literals (spec said mirror, not refactor).
+- New top-level smoke test `test_selfheal` (alias `selfheal`): a generated
+  driver sources updater.sh, re-pins RESOLV_CONF/probe-hosts/bin paths, stubs
+  dig/nslookup/curl/opkg via a PATH-prepended bin dir whose behaviour is keyed
+  off marker files, and installs a fake `/etc/init.d/netshift` that logs
+  stop/start/restart (absolute path can't be PATH-overridden — write+restore the
+  real one). 5 scenarios: preflight-pass, dns-heal, teardown-heal, heal-fail
+  (abort, binary intact), stable-install-fail (backup restored). Registered in
+  `all)`, case alias, usage line, docker-compose comment.
+- **`set -e` landmine (again)**: the worker returns non-zero on recoverable
+  failures (success:false). Calling it directly inside a test under `set -e`
+  aborts the WHOLE suite mid-run (only the passes before it print, summary never
+  runs, rc=1 with no FAIL line). Wrap the invocation `... || true` — assertions
+  read JSON/file-state, not rc. (Distinct from the task-007 `$(...)`-capture
+  variant.)
+
+## task-010: keyword filter case-fold is ASCII+Cyrillic (not just ASCII)
+
+- **`ascii_downcase` only folds ASCII A-Z** — Cyrillic server tags (e.g.
+  `Германия`) stayed mixed-case, so a Cyrillic include keyword in any other
+  case matched 0 nodes → kept=0 → blocked outbound (hardware-confirmed: include
+  `[ГеРма,пОЛЬш,рос]` over 316 outbounds gave 0 before, 28 after).
+- Fix lives in `sing_box_cf_prepare_subscription_batch`
+  (`sing_box_config_facade.sh`). That jq call does NOT `import` helpers.jq, so the
+  fold is defined **inline** at the top of the program as `def ucfold:` using only
+  `explode`/`map`/`implode` (NO Oniguruma): ASCII `65-90`→`+32`, Cyrillic
+  `1040-1071` (А-Я)→`+32`, and the single out-of-block `Ё` `1025`→`1105` (ё).
+  Everything else (emoji/other scripts) passes through unchanged → still matches
+  as exact codepoint substrings. Replaced the 3 `ascii_downcase` uses (the two
+  `$inc`/`$exc` list normalizers + the `$name | ucfold` in the select). The
+  `index()`-based `name_passes_keywords` substring logic is unchanged.
+- Cyrillic codepoints: А-Я = 1040-1071, а-я = 1072-1103 (so +32), Ё = 1025
+  sits BEFORE the block, ё = 1105 sits AFTER it — hence the special-case branch.
+- Smoke: extended the existing FBEOF block in `test_subscription` with CASE K
+  (Cyrillic). No new top-level test / registration needed — it rides the existing
+  `subscription` category. Synthetic names with literal UTF-8 (`Германия`,
+  `Орёл`, etc.) in the heredoc are fine; assert via `.count`/`.names`. Used a
+  `case "$x" in *Польша*)` membership check rather than exact-name compare for the
+  exclude case (order-independent). All ran green in-container.
+
+## task-011: keyword filter must not poison the subscription rejected-hash
+
+- Root cause of the hardware re-download loop: `mark_subscription_outbound_unavailable`
+  (`bin/netshift`) md5'd the VALID `<section>.json` and wrote it to `.rejected`
+  even when `kept=0` was caused purely by the user's keyword filter (a setting,
+  not a bad feed). Then `subscription_cache_is_usable` — which had already passed
+  `validate_subscription_file` — still returned 1 on the hash match, forcing a
+  re-download; `download_subscription_into_cache` saw tmp_hash==rejected_hash and
+  `return 14` (unchanged+rejected) → infinite retry. The poison also survived
+  loosening the filter (lived only in `.rejected`).
+- Fix A: 2nd arg `keyword_filter_active="${2:-0}"`. When 1: NEVER compute/write
+  the hash, `rm -f` the `.rejected` (self-heals a previously poisoned hash), still
+  set unavailable state + `subscription_startup_blocked=1`, warn that the FILTER
+  (not the feed) emptied the set. When 0: unchanged (genuine outbound-less body
+  still recorded → flash-loop guard kept). Caller at the `subscription)` branch
+  passes `$subscription_keyword_filter_active` (set 0/1 just above from the two
+  UCI keyword lists).
+- Fix B: in `subscription_cache_is_usable`, after `validate_subscription_file`,
+  run a jq -e "has >=1 proxy outbound" check (same predicate as the batch:
+  `[.outbounds[]? | select(.type != "selector" and ... != "block")] | length > 0`,
+  NO Oniguruma) → if true `return 0` (usable) regardless of `.rejected`. The
+  rejected-hash veto now only fires on a validated-but-outbound-less body. NB:
+  `validate_subscription_file` ALREADY requires length>0, so a 0-proxy body fails
+  validation first — B is belt-and-suspenders + self-documenting, and robust if
+  validation ever loosens. Did NOT touch `download_subscription_into_cache`'s own
+  rejected logic (spec: once A/B stop writing+vetoing, a valid body has no
+  `.rejected` so return 14 can't fire for it).
+- **Testing functions that live in `bin/netshift` (not a lib):** can't source the
+  file (it runs the dispatcher + needs LuCI `/lib/functions.sh`). Pattern that
+  works: a generated driver that (1) stubs the few helpers the target calls
+  (`log`, the `get_subscription_*_path` builders), (2) sources `helpers.sh` for
+  the real `validate_subscription_file`, (3) extracts JUST the target functions
+  verbatim with awk and `eval`s them:
+  `eval "$(awk '/^fname\(\) \{/{p=1} p{print} p&&/^\}/{exit}' "$bin")"`. Relies on
+  top-level functions closing with a column-0 `}` and having no nested column-0
+  `}` (case/if/while bodies don't). Keeps the test against shipped code, not a copy.
+- New top-level smoke test `test_rejected_hash` (alias `rejected`): 6 cases
+  (A-no-write+clear, A-recovery, B-not-vetoed, A-protected-no-proxy-still-vetoed,
+  regression-usable, A-arg0-genuine-recorded). Registered in `all)`, case alias,
+  usage "Available:" line, docker-compose comment. Same name:OK/FAIL parse + the
+  subshell-pipe PASS-counter quirk as test_subscription (suite `Results:` total
+  omits piped-while passes; the per-test ✓ marks are the source of truth).
+
+## task-012: vmess:// '#fragment' strip before base64 decode
+
+- Root cause: the `vmess)` case in `sing_box_config_facade.sh` passes the RAW
+  pre-url_decode link (`$raw_url`, kept that way by task-005 S1 to preserve `+`),
+  which STILL carries the `#fragment` (server display name, e.g. `#🇳🇱Ne`).
+  `vmess_link_to_json` only did `payload="${url#vmess://}"`, so the `#`/emoji/
+  Cyrillic bytes corrupted the base64 → decode failed → fatal. facade:72's
+  `url_strip_fragment` only touched the separate `$url`, NOT `$raw_url`, so the
+  strip MUST live inside `vmess_link_to_json`.
+- Fix (helpers.sh, ONE line): right after `payload="${url#vmess://}"` add
+  `payload="${payload%%#*}"` (POSIX longest-`#…`-suffix strip). Safe because the
+  base64 body never contains `#`; fragment-less payload = no-op. Existing
+  whitespace-strip (`tr -d ' \011\012\015'`, NOT `[:space:]`) + `=` pad loop +
+  `base64_decode` run unchanged on the fragment-free payload. Did NOT touch the
+  facade / reintroduce url_decode. VMess canonical name still comes from JSON
+  `ps`; we only drop the fragment, do not adopt it as the name.
+- Smoke: extended the existing vmess facade block in `test_sing_box_config` (`sb`
+  category — no new top-level test/registration) with a `vmess-frag-*` case:
+  `vmess://<base64(JSON)>#🇳🇱Ne`, sanity-check the link has `#`, then assert
+  server/uuid/transport/tls on the generated outbound. The existing ws/tcp/plus
+  cases (no `#`) double as the no-fragment regression. shellcheck -S error clean;
+  `all` = 76 passed / 0 failed.
+
+## task-013: sing-box-extended version diagnostic (build-suffix strip)
+
+- Root cause: `check_sing_box()` (`bin/netshift`, ~:3276) does
+  `version=$(sing-box version | awk '{print $3}')` then `patch=$(... cut -d. -f3)`.
+  Extended core prints `1.13.12-extended-2.3.2`, so `patch` became
+  `12-extended-2` → non-numeric → `[ "$patch" -ge 4 ]` errors `bad number` →
+  `❌ not compatible`. Stock cores have numeric patch so they passed.
+- Fix (Variant A′, ONE line + comment): right after the existing
+  `version=$(echo "$version" | sed 's/^v//')`, add `version=${version%%-*}`
+  (POSIX longest-`-…`-suffix strip; no fork/jq/regex). `1.13.12-extended-2.3.2`
+  → `1.13.12`; stock `1.12.0` has no `-` so unchanged; also tolerates future
+  `-beta`/`-rc`. `major`/`minor`/`patch` are already `local`; no new vars.
+- **OUT-OF-SCOPE PRE-EXISTING BUG (left untouched per spec, but flag it):** the
+  comparison chain `if [ "$major" -gt 1 ] || [ "$major" -eq 1 ] && [ "$minor"
+  -gt 12 ] || ... && [ "$patch" -ge 4 ]` has wrong precedence — POSIX `[]`
+  `&&`/`||` are equal-precedence left-associative, so it evaluates as
+  `(...) && [ "$patch" -ge 4 ]`, making the final patch test gate EVERY branch.
+  Result: `1.13.12` and even `2.0.0` evaluate to version_ok=0 (only `1.12.x>=4`
+  passes). The spec (task-013) explicitly says do NOT rewrite the chain — it
+  only fixes the non-numeric `bad number` crash. So the extended diagnostic no
+  longer errors, but a TRUE fix of "newer than 1.12.4 ⇒ compatible" needs a
+  follow-up task to correct the chain (e.g. parenthesize each branch in a
+  single `[ ]` per term or use `sort -V` like `check_requirements` does).
+- Smoke: NO new test (pure string strip, no new control flow — per spec). Reran
+  `shellcheck -S error` clean on `bin/netshift`; `smoke-tests all` = 76 passed /
+  0 failed.
+
+## task-014: route the MAIN DNS server through a proxy outbound (detour)
+
+- The cm/cf DNS primitives ALREADY accept `detour` as the last arg and merge it
+  conditionally (`+ (if $detour != "" then {detour:$detour} else {} end)`):
+  `sing_box_cf_add_dns_server` $6, `sing_box_cm_add_udp/tls_dns_server` $6,
+  `_add_https_dns_server` $8. So an EMPTY detour tag => byte-identical to the
+  pre-feature output (proven in smoke via `jq -cS` object compare of the
+  empty-tag main server vs a no-detour-arg call). Do NOT touch cm/cf for this.
+- New helper `_get_dns_detour_tag()` (bin/netshift, next to
+  `_determine_first_outbound_section`/`get_first_outbound_section`) echoes the
+  tag or "" = direct. NEVER `exit`; every fallback logs `warn` and degrades to
+  direct. Cascade: (1) `dns_via_outbound`!=1 -> "" silent; (2) explicit
+  `dns_outbound_section` valid + `section_has_configured_outbound` -> it, else
+  warn(if non-empty) + `get_first_outbound_section`; (3) no candidate -> warn+"";
+  (4) candidate connection_type block/exclusion -> warn+""; (5)
+  `subscription_outbound_is_unavailable` -> warn+"" (self-heal on fresh boot /
+  failed sub); (6) else `get_outbound_tag_by_section "$candidate"`. Mirrors
+  `get_subscription_download_proxy_address` (toggle + section + fail-safe).
+- Wired ONLY into the main `SB_DNS_SERVER_TAG` server in `sing_box_configure_dns`
+  (6th arg). Bootstrap (`SB_BOOTSTRAP_SERVER_TAG`) + FakeIP stay direct on
+  purpose (chicken-and-egg: bootstrap resolves the DoH/DoT host before the tunnel
+  is up; it's also the `domain_resolver` for a hostname main DNS). Two new UCI
+  opts documented (commented) in `etc/config/netshift`: `dns_via_outbound`(bool,
+  default 0) + `dns_outbound_section`. Read with `config_get_bool`/`config_get`
+  + safe defaults — never required live.
+- Did Req 4 (low-risk, observable): `check_dns_available` JSON gains
+  `"dns_via_outbound_tag"` (via `_get_dns_detour_tag`); `global_check` prints
+  `ℹ️ Main DNS via outbound: <tag>` or `ℹ️ Main DNS: direct` (valid-UTF-8 emoji).
+- **LuCI `config_get` always returns 0** (assign-and-succeed even when the option
+  is unset, leaving the var empty). So step-2's `config_get ... && [ -n "$var" ]`
+  detects a non-existent section purely via the EMPTY connection_type, not via rc.
+  Test stubs must mimic this (assign-then-`return 0`).
+- New top-level smoke test `test_dns_via_outbound` (alias `dnsdetour`): builds
+  on/off configs through the real cf/cm path (asserts main-has-detour,
+  bootstrap/fakeip no-detour, off no-detour, off byte-parity, both pass live
+  `sing-box check`), then awk-extracts `_get_dns_detour_tag` VERBATIM from the bin
+  and runs the 8-case cascade table with stubbed UCI + reused helpers. Registered
+  in `all)` + case alias + usage "Available:" line + docker-compose comment.
+  shellcheck -S error clean on bin + libs + install.sh; `smoke-tests all` = 76
+  passed / 0 failed (suite total unchanged because the per-line `pass` runs in a
+  piped `while` subshell — same counter quirk as test_subscription; the per-test
+  ✓ marks are the source of truth, here 15 green for dnsdetour).
+
+## task-014 (PR#11 backend fixes): nft v6 bracket + dead-code removal
+
+- **nft IPv6 `tproxy ... to` MUST bracket the address** — `tproxy ip6 to
+  "$ADDR_V6:$PORT_V6"` expands to `::1:1603`, which nftables v1.1.3 parses as a
+  BARE IPv6 address (`[::0.1.22.3]`, port 1603 read as 0x1603 hextet) with NO
+  port. `nft -c` PASSES and `sing-box check` is unrelated — neither gate catches
+  it; only on-device IPv6 breaks. Fix: `tproxy ip6 to "[$ADDR_V6]:$PORT_V6"`.
+  Verify with the no-root trick: write the rule to /tmp/t.nft and
+  `unshare -rn sh -c 'nft -f /tmp/t.nft && nft list ruleset' | grep tproxy` —
+  bracketed form normalizes to `tproxy ip6 to [::1]:1603` (correct). The IPv4
+  `tproxy ip to "$ADDR:$PORT"` is fine (IPv4 has no `:` ambiguity). sing-box
+  inbounds (`sing_box_cm_add_*_inbound` address+port as SEPARATE jq args ->
+  JSON `listen`/`listen_port`) have NO bracket defect — don't "fix" them.
+- **Router-originated traffic is DIRECT by design** (operator decision A). The
+  PR's model marks only LAN/forwarded traffic in `mangle` (prerouting) and
+  splits proxy/direct in sing-box; `mangle_output` only carries local/loopback
+  daddr returns + the `NFT_OUTBOUND_MARK` return (so sing-box-originated packets
+  don't loop back into tproxy). Documented with a comment; no behavior change.
+- **The `@netshift_subnets` (`NFT_COMMON_SET_NAME`) nft set was fully dead** —
+  created + populated at 6 sites but matched by NO nft rule after PR#11. SAFE to
+  remove because every subnet source is independently carried into a sing-box
+  rule_set: user_subnets -> `patch_source_ruleset_rules ip_cidr` + local source
+  ruleset; local_subnet_lists -> `import_plain_subnet_list_to_local_source_ruleset_chunked`;
+  community_lists -> `configure_community_list_handler` (`$SRS_MAIN_URL/<svc>.srs`
+  remote ruleset); remote json/srs subnets -> `configure_remote_domain_or_subnet_list_handler`
+  (`sing_box_cm_add_remote_ruleset`); remote plain -> `prepare_source_ruleset` +
+  plain import. DISCORD is the ONE exception that still needs an nft set
+  (`NFT_DISCORD_SET_NAME`) — it has a live dport-restricted mangle rule
+  (`@netshift_discord_subnets udp dport {19000-20000,50000-65535}`) that a
+  sing-box route rule can't express. Removed: set creation (~972), all 6
+  `nft_add_set_elements*` populate calls, the now-orphaned
+  `import_subnets_from_remote_json_file`/`_srs_file` (json/srs now log
+  "sing-box manages updates" like the domains path), `netshift_subnets` from the
+  diagnostics `sets` list, and the `NFT_COMMON_SET_NAME` constant. Left the 9
+  IPv4 `SUBNETS_*` constants (only `SUBNETS_DISCORD` used) in place — constants.sh
+  is `# shellcheck disable=SC2034` so unused-looking vars don't fail lint, and
+  trimming them was out of declared scope.
+- **8 `SUBNETS_*_V6` constants had zero consumers** (`git grep` only matched
+  definitions + a memory doc) — removed.
+- **B-09 dead predicates**: `is_ip`/`is_ipv6_cidr`/`is_ipv6` in helpers.sh were
+  all unused (`is_ipv6` only called by the other two; tests use only `is_ipv4`/
+  `url_is_ipv6_literal`/`is_ipv4_ip_or_ipv4_cidr`). Removed all three.
+- **Monitor spawn guard (B-05)**: extracted `start_sing_box_monitor` mirroring
+  the `start_subscription_startup_retry_worker` pidfile-guard — if
+  `/var/run/netshift_monitor.pid` exists and `kill -0 "$pid"` succeeds, skip the
+  spawn (else `rm` stale pidfile then spawn). Prevents a procd double-start from
+  orphaning a monitor that `stop()` can no longer kill.
+- **B-08 dnsmasq guard (review-001 FIX — sentinel, not markers)**: my first B-08
+  attempt gated `dnsmasq_is_configured_for_netshift` on the presence of a private
+  backup marker (`netshift_server`/`netshift_noresolv`/`netshift_cachesize`).
+  That was WRONG and regressed STOCK dnsmasq: on a default box with no original
+  server/noresolv/cachesize, `dnsmasq_configure` writes NO markers
+  (`backup_dnsmasq_config_option` only writes when the original value is
+  non-empty; the server-backup loop is skipped when current servers are empty).
+  So the guard returned false, and the redundant `dnsmasq_configure force` path
+  (monitor recovery restart, double-start) re-ran "backup" — but the LIVE values
+  were now netshift's OWN (noresolv=1, cachesize=0), so it captured those as the
+  backup -> `dnsmasq_restore` later restored 1/0 instead of the OpenWRT defaults
+  (0/150) -> router DNS broken after stop/uninstall.
+  CORRECT fix = an explicit netshift-owned SENTINEL: `dnsmasq_configure` does
+  `uci_set "dhcp" "@dnsmasq[0]" "netshift_configured" 1` UNCONDITIONALLY right
+  after applying our config (before the commit); `dnsmasq_is_configured_for_netshift`
+  short-circuits iff `netshift_configured == 1` (authoritative ownership flag, no
+  value/marker inference); `dnsmasq_restore` clears it with `uci_remove_quiet`
+  before its commit so a fresh future configure re-establishes ownership. The
+  sentinel is a distinct option name (not in the `server` list), so it never
+  leaks into the server/backup iteration. Verified all 3 scenarios via an
+  awk-extracted-functions harness (use an EXACT-match UCI stub — `awk -F'\t'
+  $1==k`, NOT grep/sed, because the literal `@dnsmasq[0]` key contains `[0]`
+  which a regex reads as a char class and silently mis-reads every lookup):
+  (A) stock -> sentinel set, no spurious backup, force-again short-circuits,
+  restore=0/150, sentinel cleared; (B) admin-had-config -> real values backed up
+  & restored intact; (C) coincidental admin match w/o sentinel -> NOT treated as
+  owned. shellcheck clean; smoke 81/0.
+- shellcheck -S error clean (bin + libs + install.sh); `smoke-tests all` = 81
+  passed / 0 failed (unchanged baseline). No new smoke test (separate packaging
+  task owns nft/v6 coverage per spec). No sacred constant VALUES changed.
+
+## task-017: Component Manager backend (stock latest, NetShift self-update)
+
+- **Two new component_action() cases** (`updater.sh` ~:1612): `sing_box:
+  check_update_stable) updates_check_sing_box_stable` (SYNC) and
+  `netshift:self_update) updates_self_update_netshift` (async via the existing
+  `component_action_async`). NO dispatcher (bin/netshift) change — both are
+  sub-cases of the already-routed `component_action`; `component_action_async`/
+  `_status` are component-agnostic. NO ACL change.
+- **pkg-manager abstraction re-implemented locally** (updater.sh does NOT source
+  install.sh): `updates_pkg_is_apk` (`command -v apk`), `updates_pkg_install_file`
+  (apk add --allow-untrusted / opkg install, `</dev/null` non-interactive),
+  `updates_pkg_is_installed` (apk/opkg list grep), `updates_pkg_candidate_version`
+  (FEED version). Candidate parse, busybox-safe, NO Oniguruma: opkg `list <pkg>`
+  → `"<name> - <ver>"`, `awk -F' - ' '{print $2}'`; apk `list <pkg>` → first
+  token `<name>-<ver>`, strip `"<pkg>-"` prefix via `${line#"$pkg"-}`.
+- **Stock check `updates_check_sing_box_stable`**: mirrors the extended-check JSON
+  shape. Runs `opkg/apk update` best-effort first (`|| true`). status: candidate
+  empty → `success:false` (feed unreachable, return 1); sing-box absent
+  (`command -v`) → `not_installed`; else compare on LEADING semver `${v%%-*}`
+  (drops `-r1`/`-extended-…`) via `is_min_package_version` (sort -V) →
+  `latest`/`outdated`. NEVER exits. STABLE JSON: `{success,current_version,
+  latest_version,status:"latest"|"outdated"|"not_installed"}`.
+- **NetShift self-update = Variant A** (targeted pkg upgrade, NOT install.sh).
+  `updates_self_update_netshift` (public wrapper) COPIES the
+  `updates_install_sing_box_extended` epilogue EXACTLY: reset UPDATES_HEAL_*,
+  `updates_ensure_connectivity "extended"` (GitHub dir) else restore+fail JSON,
+  run `_updates_self_update_netshift_core >"$out"`, capture rc+json, rm, ALWAYS
+  `updates_restore_after_swap`, re-emit, `return $rc`. Single cleanup path; no
+  trap. Core is NON-interactive, all `local`, NEVER `exit`: idempotent guard
+  (`${installed#v}` == `${latest#v}` → "Already up to date"); minimal
+  `/etc/config/netshift` tmpfs backup; download assets matching pkg-name prefixes
+  (`netshift`,`luci-app-netshift`, RU i18n ONLY if `updates_pkg_is_installed`)
+  filtered to `.ipk`/`.apk` by pkg-mgr via `grep -o 'https://[^"[:space:]]*\.ext'`
+  (mirrors install.sh:269-274, busybox-safe); install core→luci→ru; core-install
+  fail is fatal-to-the-op (success:false + restore config), luci/ru fail is
+  non-critical (warn+continue); defensive config restore if live file empty.
+- **Self-replacement CONFIRMED safe**: the `netshift` pkg overwrites
+  `/usr/bin/netshift` (this very script). busybox ash reads the whole script into
+  memory before pkg_install; the async fork (`( trap '' HUP; "$0" component_action
+  netshift self_update >out; updates_write_finished_job_state ... )`) + the
+  finished-state write complete from memory. The self-update core has ZERO live
+  re-exec after install: NO `updates_restart_netshift`, NO `"$0"`, NO `exec`, NO
+  direct `/usr/bin/netshift` or `/etc/init.d/netshift` call. (Only path that runs
+  the init script is `updates_restore_after_swap`'s `/etc/init.d/netshift start`,
+  which fires ONLY if the heal tore the redirect down, AFTER install completes,
+  as a fresh subprocess that safely loads the on-disk binary.) UI (task-018)
+  reloads the page after success. Verified via `grep` of the core's line range.
+- **New constants** (constants.sh, NO ports/marks): `NETSHIFT_RELEASE_API_URL`
+  (= install.sh REPO / get_system_info :3347 endpoint),
+  `UPDATES_NETSHIFT_DOWNLOAD_DIR=/tmp/netshift/selfupdate`,
+  `UPDATES_NETSHIFT_CONFIG_BACKUP=/tmp/netshift/config.bak`,
+  `UPDATES_NETSHIFT_PKG_CORE/LUCI/I18N_RU`. `get_system_info` UNCHANGED (UI gets
+  versions there; stock check is a separate action — no missing field).
+- **Subshell-piped `while read url` loop can't set parent vars** (task-007
+  variant): `_updates_self_update_download_assets` re-checks the dir
+  (`ls "$dir/netshift"*`) AFTER the loop to decide success, not a flag set inside.
+- **Smoke tests `test_check_update_stable` (alias `stablecheck`, 4 cases) +
+  `test_self_update_netshift` (alias `selfupdate`, 13 assertions)**. Both source
+  the REAL updater.sh + helpers.sh, re-pin paths/constants, stub via markers.
+  `test_check_update_stable` KEY GOTCHA: `command -v sing-box` finds the real
+  `/usr/bin/sing-box`; to test `not_installed` I built an ISOLATED PATH dir of
+  symlinks to just the needed coreutils (NO /usr/bin in PATH) and linked the fake
+  sing-box in/out per scenario. `test_self_update_netshift` overrides
+  `updates_http_get_once` (GitHub JSON) + `updates_download_to_file` in the driver
+  + stubs opkg `install`/`list-installed` (logs installs) + fake `/etc/init.d/
+  netshift` (absolute write+restore). Registered all 5 points (all)/case/usage/
+  compose). Used task-009 `... || true` set -e guard. shellcheck -S error clean;
+  `smoke-tests all` = 101 passed / 0 failed (was 84 baseline; +17 new).
+
+## task-019: extended-check false "outdated" — v-prefix mismatch (Variant A)
+
+- Root cause: `updates_check_sing_box_extended` (updater.sh ~:1245) compared
+  installed `get_sing_box_version` (`1.13.12-extended-2.3.2`, NO v) against the
+  GitHub `.tag_name` (`v1.13.12-extended-2.3.2`, WITH v) via `case
+  "$current_version" in *"$tag"*)`. The `v` prefix means the substring never
+  matched → fell through to `outdated` for a user ALREADY on the latest. (Stock
+  check + self-update were already correct: stock candidates have no v;
+  `_updates_self_update_netshift_core` already does `${installed#v}` ==
+  `${latest#v}`.)
+- Fix (Variant A, ONLY this function): strip a single leading v off BOTH sides
+  (`cur_norm="${current_version#v}"; tag_norm="${tag#v}"`; `${x#v}` removes one
+  leading v if present, no-op otherwise), then EXACT-compare `[ "$cur_norm" =
+  "$tag_norm" ]` (the extended version is the full token — exact-after-v-strip is
+  correct and avoids the partial matches the old `case *"$tag"*` allowed). Emit
+  BOTH `current_version` and `latest_version` v-stripped so the UI shows a
+  consistent string. JSON shape/keys/order unchanged (STABLE for task-018);
+  `success:false` branches (fetch fail, no tag) untouched. New vars `local`,
+  POSIX ash, never exits.
+- CRITICAL isolation: the install/asset path is a SEPARATE function
+  (`_updates_install_sing_box_extended_core`, ~:942-957) that re-derives its OWN
+  `tag` from `updates_extended_release_tag` (raw, WITH v) and feeds it to
+  `updates_extended_release_object` (`.tag_name == $t`) + `updates_extended_asset_url`.
+  In the check, `tag` (raw) is NO LONGER fed anywhere downstream — only `cur_norm`/
+  `tag_norm`. Did NOT touch `_release_tag`/`_release_object`/`_asset_url`/wrappers.
+- Smoke: NEW top-level `test_check_update_extended` (alias `extcheck`, 3 cases).
+  updater.sh is a sourceable lib, so the driver sources updater.sh + helpers.sh,
+  silences log/echolog/nolog, then OVERRIDES the 3 deps AFTER sourcing
+  (`get_sing_box_version`, `updates_fetch_sing_box_extended_releases`,
+  `updates_extended_release_tag`) reading marker env (`STUBEXT_INSTALLED/RELEASES/TAG`)
+  — simpler than awk-extract since it's not in bin/netshift. Cases: (1) installed
+  == latest, only tag has v → latest + both v-stripped+equal (THE regression);
+  (2) installed older → outdated; (3) empty releases → success:false. Registered
+   all 5 points (all)/case/usage/docker-compose comment). shellcheck -S error clean
+   (bin+libs+install.sh); `smoke-tests all` = 104 passed / 0 failed (101 baseline
+   + 3 new). `extcheck` alone = 3/0.
+
+## task-020a: drop stale "mangle output counters" diagnostic (PR#11 B-02 align)
+
+- The diagnostic function the spec calls `check_nft` is actually named
+  **`check_nft_rules`** in bin/netshift. After PR#11 (router-originated traffic
+  intentionally DIRECT) the `mangle_output` chain's only counter rule
+  (`meta mark 0x00200000 counter return`) is essentially never hit → counter
+  legitimately 0 → the old non-zero-counter assertion produced a FALSE ⚠️.
+  Operator decision Variant A = REMOVE the "mangle output counters" check
+  entirely; KEEP "mangle output exist".
+- Backend fix (bin/netshift ONLY, 6 deletions): in `check_nft_rules` removed the
+  `rules_mangle_output_counters` local, the inner `grep -qv "packets 0 bytes 0"`
+  block that set it, and the key from the emitted JSON echo. In `global_check`
+  removed it from the `local` decl, its `jq -r '.rules_mangle_output_counters //
+  0'` read, and the `if ... ✅/⚠️ Rules mangle output counters` print block.
+  KEPT the existence check (`grep -q "counter" → rules_mangle_output_exist=1`)
+  and its ✅/❌ print. Did NOT touch mangle(prerouting)/proxy/other_mark or
+  `create_nft_rules`.
+- **STABLE check_nft_rules JSON shape (cross-layer contract for frontend 020b),
+  exactly ONE key removed, order otherwise unchanged:** `{table_exist,
+  rules_mangle_exist, rules_mangle_counters, rules_mangle_output_exist,
+  rules_proxy_exist, rules_proxy_counters, rules_other_mark_exist}`.
+- **No smoke test referenced the field** — `tests/entrypoint.sh` has no
+  `test_diagnostics`/nft-check assertion on the check_nft_rules JSON at all (the
+  `nft` category tests rule installation, not the diagnostic JSON keys). So no
+  smoke change and no registration change. Diagnostics-only edit (read-only
+  checks), NOT a routing/config change — nft model unchanged. shellcheck -S error
+  clean; `smoke-tests all` = 104 passed / 0 failed (unchanged baseline); UTF-8
+  intact (iconv round-trip OK, 0 рџ/в”/†mojibake).
+
+## task-021b: opt-in insecure subscription fetch (--no-check-certificate)
+
+- Cross-layer UCI contract (STABLE, shared with 021a frontend):
+  `option subscription_insecure '0'` (0|1), per `config section`. Default OFF =
+  unchanged secure behavior. On device wget=uclient-fetch supports
+  `--no-check-certificate` (confirmed) — for IP-host panels with invalid/
+  self-signed/missing-SAN HTTPS certs.
+- `download_subscription` (helpers.sh) had SIX identical wget invocations (4 in
+  the main loop: ipv4/normal × proxy/no-proxy + 2 in the IPv4 retry), each with
+  the same 7 `--header` set. Refactored ALL six through a new private helper
+  `_wget_subscription_request "$cert_flag" UA HWID MODEL KERNEL OUT ERR URL --
+  <leading flags>`: it runs `wget $cert_flag "$@" -O "$out" <headers> "$url"
+  2>"$err"`. The `$cert_flag` is the ONE intentional unquoted expansion
+  (`# shellcheck disable=SC2086` on that line): empty string word-splits to ZERO
+  args (byte-identical secure default), `--no-check-certificate` adds exactly
+  one. NO eval. Per-branch `-4`/`-T <timeout>` are passed as the trailing
+  `"$@"` flags; proxy env (`http_proxy=`/`https_proxy=`) still set on the call
+  line. Retry/fallback/rc/mv/errfile logic untouched.
+- 8th positional `insecure="${8:-0}"`; `cert_flag` derived once at top
+  (`[ "$insecure" = "1" ]`).
+- bin/netshift `download_subscription_into_cache`: read
+  `subscription_insecure="$(uci -q get "netshift.${section}.subscription_insecure"
+  2>/dev/null)"`, default 0, log ONE redacted `warn`
+  (`...uses --no-check-certificate (TLS verification disabled): url=$(redact_url_for_log ...)`)
+  when =1, pass as the NEW 8th arg after the existing
+  `... 3 2 10 "$effective_user_agent"`. Declared `local subscription_insecure`.
+- UCI example: added commented `#option subscription_insecure '0'` + 3-line
+  comment near the `subscription_url` example in `etc/config/netshift`.
+- Smoke: NEW top-level `test_insecure_fetch` (alias `insecure`, 6 cases). A
+  PATH-prepended fake `wget` records full argv (`printf '%s\n' "$*"`) and writes
+  a dummy body to its `-O` target so attempt-1 succeeds (no retry). Driver
+  sources REAL helpers.sh, stubs log/metadata helpers + `should_force_wget_ipv4`
+  (per-scenario normal vs ipv4) + inert `has_ipv4_default_route`/
+  `wget_supports_ipv4_flag`. Asserts `--no-check-certificate` ABSENT@insecure=0 /
+  PRESENT@insecure=1 across normal+proxy+ipv4 branches (`-4` co-present on ipv4).
+  Registered all 5 points (all)/case alias/usage line/docker-compose comment).
+  shellcheck -S error clean; `smoke-tests all` = 110 passed / 0 failed (104
+  baseline + 6 new); UTF-8/LF intact. Additive, NO runtime-contract change.

docs/agent-rules/packaging.md

@@ -0,0 +1,188 @@
+# Agent Rules: Packaging, CI & Release
+
+Authoritative rules for building, testing, and releasing NetShift. Read this
+before touching anything below.
+
+**Scope:** `netshift/Makefile`, `luci-app-netshift/Makefile`,
+`Dockerfile-ipk`, `Dockerfile-apk`, `sdk/`, `tests/`, `.github/workflows/`,
+`install.sh`.
+
+---
+
+## 1. The packages
+
+Two source packages produce three published artifacts:
+
+- **`netshift`** — the backend (init script, UCI config, `/usr/bin/netshift`,
+  shell + jq libs under `/usr/lib/netshift`).
+- **`luci-app-netshift`** — the web UI. Its Makefile sets
+  `LUCI_LANGUAGES := en ru`, so the build also emits
+  **`luci-i18n-netshift-ru`** (the Russian translation) as a third package.
+
+Both packages are `PKGARCH := all` / `LUCI_PKGARCH := all` (architecture-
+independent).
+
+---
+
+## 2. `netshift/Makefile` (backend)
+
+- `DEPENDS := +sing-box +curl +jq +kmod-nft-tproxy +coreutils-base64
+  +bind-dig`
+- `CONFLICTS := https-dns-proxy nextdns luci-app-passwall luci-app-passwall2`
+- Version:
+  `PKG_VERSION := $(if $(NETSHIFT_VERSION),$(NETSHIFT_VERSION),0.$(shell date +%d%m%Y))`
+  — i.e. use `NETSHIFT_VERSION` when set, otherwise a date-stamped fallback.
+- `Package/netshift/prerm` removes the `105 netshift` line from
+  `/etc/iproute2/rt_tables` (only if present) and runs
+  `/etc/init.d/netshift stop`. **Service/system-state teardown lives in the
+  package `prerm`, not in `install.sh`.**
+- `Package/netshift/conffiles` declares `/etc/config/netshift` (preserved
+  across upgrades).
+- Version stamp: `Package/netshift/install` runs
+  `sed -i -e 's/__COMPILED_VERSION_VARIABLE__/$(PKG_VERSION)/g'
+  $(1)/usr/lib/netshift/constants.sh` — **no `|| true`** (this stamp must
+  succeed).
+
+`luci-app-netshift/Makefile` stamps the **same** placeholder into the bundled
+UI: `sed -i -e 's/__COMPILED_VERSION_VARIABLE__/$(PKG_VERSION)/g'
+.../view/netshift/main.js || true` — note the **`|| true`** here (UI stamp is
+best-effort). It uses the same `PKG_VERSION` expression and
+`LUCI_DEPENDS := +luci-base +netshift`.
+
+> If you ever rename `__COMPILED_VERSION_VARIABLE__`, update **both** Makefile
+> `sed`s and `fe-app-netshift/src/constants.ts` together. See
+> `frontend-luci.md` §6.
+
+---
+
+## 3. Docker build images
+
+- `Dockerfile-ipk` — `FROM itdoginfo/openwrt-sdk-ipk:24.10.6`.
+- `Dockerfile-apk` — `FROM itdoginfo/openwrt-sdk-apk:25.12.3`.
+- Both copy `./netshift` → `feeds/utilities/netshift` and
+  `./luci-app-netshift` → `feeds/luci/luci-app-netshift`, then run
+  `make defconfig` + `make package/<pkg>/compile`.
+- `sdk/Dockerfile-sdk-ipk` (`FROM openwrt/sdk:x86_64-v24.10.6`) and
+  `sdk/Dockerfile-sdk-apk` (`FROM openwrt/sdk:x86_64-v25.12.3`) are the **base
+  SDK images** that the `itdoginfo/openwrt-sdk-*` images derive from (feeds
+  updated, `luci-base` installed, feed dirs created; the apk one also runs
+  `./setup.sh`).
+
+### KNOWN INCONSISTENCY — respect it, do not "fix" blindly
+
+The two release Dockerfiles pass the version differently:
+
+- `Dockerfile-ipk`: `RUN export NETSHIFT_VERSION="v${NETSHIFT_VERSION}" && ...`
+  — it **prepends `v`**.
+- `Dockerfile-apk`: `ENV NETSHIFT_VERSION=${NETSHIFT_VERSION}` — **raw, no
+  `v`**.
+
+This asymmetry is intentional/load-bearing for the current artifact names. Do
+not normalize one to match the other without verifying the whole release flow
+(§4) and `install.sh` matching (§6).
+
+---
+
+## 4. Release flow (`.github/workflows/build.yml`)
+
+Triggered on **tag push** (`tags: ['*']`). Jobs:
+
+1. **`smoke-tests`** — builds and runs the OpenWRT rootfs smoke suite
+   (`docker compose -f tests/docker-compose.yml run --rm netshift-test all`).
+   This is a **gate**: `build` `needs` it.
+2. **`preparation`** — derives the version:
+   `git describe --tags --exact-match || "0.$(date +%d%m%Y)"`.
+3. **`build`** (matrix `ipk` + `apk`) — builds via
+   `Dockerfile-<type>`, passing `NETSHIFT_VERSION` from `preparation`; then
+   `docker create` + `docker cp` the built packages out of
+   `/builder/bin/packages/x86_64/{utilities,luci}/`.
+4. **ipk-only rename** — for `ipk`, every `*.ipk` filename is rewritten with
+   `sed 's/_/-/g'` (underscore → dash).
+5. **Filter** — copies exactly the **three** packages into `filtered-bin/`:
+   `luci-i18n-netshift-ru-*`, `netshift-*`, `luci-app-netshift-*` (the i18n
+   one is renamed to carry `${VERSION}`).
+6. **`release`** — downloads both matrices' artifacts and publishes a
+   **GitHub Release** (`softprops/action-gh-release`) named/tagged
+   `github.ref_name`.
+
+The underscore→dash rename (step 4) is **load-bearing**: `install.sh` matches
+release assets by **package-name prefix** (see §6), and the dashed names are
+what it expects.
+
+---
+
+## 5. Smoke tests (`tests/`)
+
+- Runs in an **OpenWRT 24.10.6 rootfs** container (`tests/Dockerfile`: pulls
+  the official `openwrt-24.10.6-x86-64-rootfs.tar.gz`, `opkg install`s
+  `sing-box curl jq coreutils-base64 bind-dig nftables`).
+- Source is **bind-mounted read-only**: `../netshift/files` →
+  `/netshift/files:ro` (see `tests/docker-compose.yml`). The container has no
+  copy of the scripts — it tests the live source tree.
+- Requires kernel caps **`NET_ADMIN` + `NET_RAW` + `SYS_ADMIN`** and
+  `network_mode: host` (for real nft / DNS operations).
+- `entrypoint.sh` `main()` dispatches by category. The `all` target runs, in
+  order: `test_deps test_syntax test_config test_helpers test_jq_helpers
+  test_config_manager test_sing_box_config test_nft test_diagnostics
+  test_subscription`. The usage line lists:
+  `all deps syntax config helpers jq cm sb nft diagnostics subscription`.
+
+### How to ADD a smoke test
+
+1. Write a `test_xyz()` function using the existing helpers:
+   `header`, `pass`, `fail`, `skip` (they drive the `PASS`/`FAIL`/`SKIP`
+   counters and `summary`). For sub-shells, emit `name:OK` / `name:FAIL` /
+   `name:SKIP` lines and let the `case` parser pick them up (see
+   `test_helpers` / `test_subscription`).
+2. Add it to the `all)` list in `main()`.
+3. Add a short **case alias** (e.g. `xyz) test_xyz ;;`).
+4. Update the **usage line** in `main()` (the `Available: ...` echo).
+5. Update the **`docker-compose.yml` comment** that documents test names.
+
+---
+
+## 6. CI gates by path
+
+| Workflow | Triggers (paths) | What it does |
+|---|---|---|
+| `frontend-ci.yml` | `fe-app-netshift/**` (PR) | `yarn install --frozen-lockfile`, `yarn format` (fail on diff), `yarn lint --max-warnings=0`, `yarn test --run`, `yarn build` (fail on diff). See `frontend-luci.md`. |
+| `shellcheck.yml` | `install.sh`, `netshift/files/usr/bin/**`, `netshift/files/usr/lib/**` (push/PR to `main`/`rc/**`) | Differential ShellCheck, `severity: error`, include-paths `netshift/files/usr/bin/netshift`, `netshift/files/usr/lib/**.sh`, `install.sh`. |
+| `openwrt-smoke-tests.yml` | `netshift/**`, `luci-app-netshift/**`, `tests/**`, `install.sh`, `Dockerfile-ipk`, `Dockerfile-apk`, `.dockerignore` (push/PR to `main`/`rc/**`) | Builds the smoke image and runs `netshift-test all`. |
+
+> **Keep the two smoke invocations in sync.** `build.yml`'s `smoke-tests` job
+> runs the suite **only on tag push**; PR/branch coverage comes from the
+> separate `openwrt-smoke-tests.yml`. Both call
+> `docker compose -f tests/docker-compose.yml ... netshift-test all` — if you
+> change one compose command (image name, target, flags), change the other.
+
+---
+
+## 7. `install.sh`
+
+- **POSIX `sh`** (BusyBox `ash` compatible); shellcheck-gated at `error`.
+- **Package-manager abstraction:** detects `apk` (`PKG_IS_APK=1`) vs `opkg`
+  and wraps install/remove/update/list (`pkg_install`, `pkg_remove`,
+  `pkg_is_installed`, etc.). apk install uses `--allow-untrusted`; opkg remove
+  uses `--force-depends`.
+- **podkop → netshift migration** (`migrate_from_podkop`, triggered by
+  `podkop_is_installed` since podkop never reached 0.8.0): **stop the old
+  service first** (`/etc/init.d/podkop stop` then `disable`) so dnsmasq/nft
+  teardown happens, **back up config** to
+  `/etc/config/podkop.bak.pre-netshift`, copy config to
+  `/etc/config/netshift`, remove the original `/etc/config/podkop`, clean the
+  old `105 podkop` rt_tables line and podkop cron entries, and remove the old
+  `luci-i18n-podkop*` / `luci-app-podkop` / `podkop` packages.
+- **OpenWRT 23.05 is unsupported** (since NetShift 0.8.0): `check_system`
+  exits if `DISTRIB_RELEASE` major == `23`.
+- **Space requirement:** needs **≥ 15 MB** free in `/overlay`
+  (`REQUIRED_SPACE=15360` KB).
+- **Asset matching:** scrapes the latest-release API
+  (`https://api.github.com/repos/yandexru45/netshift/releases/latest`),
+  greps `.apk`/`.ipk` URLs, then installs by **package-name prefix**
+  (loops `for pkg in netshift luci-app-netshift`, plus
+  `luci-i18n-netshift-ru*`). This is why the ipk underscore→dash rename in
+  `build.yml` (§4) is load-bearing.
+- **NO uninstall path.** `install.sh` only installs/migrates; removal lives in
+  the package `prerm` (see §2). Do not add an uninstaller here.
+- **Known fragility:** GitHub API **rate limiting** — the script detects
+  `API rate limit` and exits with a "repeat in five minutes" message.

docs/agent-rules/project-core.md

@@ -0,0 +1,112 @@
+# NetShift — Project Core Rules (AUTHORITATIVE)
+
+> Single source of truth for AI agents working anywhere in this repo. Read this before touching code. Every rule below is grounded in the actual source — do not invent values.
+
+## 1. Project identity
+
+NetShift is an OpenWRT traffic router built on top of [sing-box](https://github.com/SagerNet/sing-box): it selectively routes chosen domains/subnets through a tunnel and sends everything else directly. It is a fork of [itdoginfo/podkop](https://github.com/itdoginfo/podkop), rebranded to NetShift at version `0.8.0`. The project is **beta** (expect breaking changes). License: **GPL-2.0-or-later** (`LICENSE`), with a **separate trademark policy** — the NetShift name and logos are protected; see `TRADEMARK.md`. Code is GPL-licensed; the brand is not.
+
+Hard requirements (target device):
+- OpenWRT **24.10+**
+- `sing-box >= 1.12.0` (`SB_REQUIRED_VERSION` in `constants.sh`)
+- `jq >= 1.7.1` (`JQ_REQUIRED_VERSION`)
+- `coreutils-base64 >= 9.7` (`COREUTILS_BASE64_REQUIRED_VERSION`)
+- `>= 25 MB` free space (16 MB flash devices unsupported)
+
+## 2. The three packages and strict dependency direction
+
+Layers point in ONE direction. **No layer skips another.**
+
+```
+luci-app-netshift  (TS/LuCI UI, hand-written views + generated main.js)
+        │  consumes the generated main.js produced from
+        ▼
+fe-app-netshift    (TypeScript source, built with tsup)
+        │  UI talks ONLY to the backend, never to sing-box/nft/dnsmasq directly
+        ▼
+netshift backend   via LuCI fs.exec of /usr/bin/netshift and /etc/init.d/netshift (ACL-gated)
+        │
+        ▼
+sing-box / nftables / dnsmasq
+```
+
+- `luci-app-netshift` — LuCI web UI. Its `htdocs/.../view/netshift/main.js` is **generated** from `fe-app-netshift`. Hand-written views live alongside it.
+- `fe-app-netshift` — the TypeScript source of `main.js` (fetchers, methods, services, tabs). Edit UI logic **here**, not in the generated bundle.
+- `netshift` — the backend package (POSIX ash + jq): CLI dispatcher `/usr/bin/netshift`, procd init `/etc/init.d/netshift`, libraries in `/usr/lib/netshift/`, UCI config `/etc/config/netshift`.
+
+The UI never reimplements backend logic; it invokes backend commands. The backend never depends on the UI.
+
+## 3. Runtime contract (sacred — do not change casually)
+
+These values are wired across `constants.sh`, `nft.sh`, the CLI, and the generated sing-box config. Changing one without the rest breaks the whole chain.
+
+| Concept | Value | Source constant |
+|---|---|---|
+| tproxy inbound | `127.0.0.1:1602` | `SB_TPROXY_INBOUND_ADDRESS` / `SB_TPROXY_INBOUND_PORT` |
+| DNS inbound | `127.0.0.42:53` | `SB_DNS_INBOUND_ADDRESS` / `SB_DNS_INBOUND_PORT` |
+| Service mixed inbound | `127.0.0.1:4534` | `SB_SERVICE_MIXED_INBOUND_*` |
+| Clash API controller | `:9090` | `SB_CLASH_API_CONTROLLER_PORT` |
+| FakeIP range | `198.18.0.0/15` | `SB_FAKEIP_INET4_RANGE` |
+| nft FakeIP mark | `0x00100000` | `NFT_FAKEIP_MARK` |
+| nft outbound mark | `0x00200000` | `NFT_OUTBOUND_MARK` |
+| nft table | `NetShiftTable` (family `inet`) | `NFT_TABLE_NAME` |
+| routing table | `105 netshift` | `RT_TABLE_NAME` + `/etc/iproute2/rt_tables` |
+| state dir | `/etc/netshift` | `NETSHIFT_STATE_DIR` |
+| sing-box config | `/etc/sing-box/config.json` (UCI `settings.config_path`) | UCI |
+
+These ports, marks, addresses, the nft table name, and the routing table id are **sacred**. They are referenced in `nft.sh` rules, `route_table_rule_mark`, dnsmasq integration (`127.0.0.42`), diagnostics (`check_sing_box`, `check_nft_rules`, `check_dns_available`), and the generated config. Treat any change to them as a system-level change (§4).
+
+## 4. System-level change rule
+
+A change is **system-level** if it touches any of:
+- nft rules / sets / chains, routing rules or tables, fwmarks
+- sing-box config schema or generation
+- dnsmasq integration (server `127.0.0.42`, `noresolv`, `cachesize`, backup/restore)
+- UCI schema (`/etc/config/netshift`)
+- ports / marks / tags in `constants.sh`
+- packaging (`Makefile`, install, conffiles, dependencies)
+- the payment-free subscription flow (download → validate → cache → generate outbounds)
+
+For system-level changes you MUST verify the **whole chain**, not a single file:
+
+```
+UCI (config_get) → config generation (sing_box_*) → sing-box -c <file> check → nft rules → running service
+```
+
+Validate by running the smoke tests and, where relevant, confirming the generated config still passes `sing-box check` and the nft table/routing still install (see `start_main` in `/usr/bin/netshift`).
+
+## 5. Repo-wide conventions
+
+- **LF line endings everywhere.** `.gitattributes` enforces `* text=auto eol=lf`. Never introduce CRLF.
+- **No magic strings.** All ports, IPs, marks, tags, paths, versions, and service lists live in `netshift/files/usr/lib/constants.sh`, grouped as `## Common`, `## nft`, `## sing-box`, `## Lists`. New constants go there.
+- Community service list is `COMMUNITY_SERVICES` in `constants.sh`; the UI and `validate_service` both depend on it.
+
+## 6. Mandatory quality gates (CI a contributor must pass)
+
+These gate every PR. Use the matching skills.
+
+1. **ShellCheck** (`.github/workflows/shellcheck.yml`) — severity `error`, over:
+   - `install.sh`
+   - `netshift/files/usr/bin/netshift`
+   - `netshift/files/usr/lib/**.sh`
+   - Skill: `shellcheck`.
+2. **OpenWRT smoke tests** (`.github/workflows/openwrt-smoke-tests.yml`) — runs `tests/entrypoint.sh` in an OpenWRT rootfs via `tests/docker-compose.yml` (`run --rm netshift-test all`).
+   - Skill: `smoke-tests`.
+3. **Frontend `yarn ci`** (in `fe-app-netshift`) — defined as:
+   `yarn format && yarn lint --max-warnings=0 && yarn test --run && yarn build`
+   i.e. prettier (no diff), ESLint with `--max-warnings=0`, vitest, and a build that must produce no diff in the committed `main.js`.
+   - Skill: `frontend-ci`.
+
+## 7. Contribution gating
+
+- `CODEOWNERS = @yandexru45`.
+- PRs are accepted **only after coordination with the authors via Telegram** (per README; see `t.me/netshift_chat`).
+- **Agents NEVER auto-commit.** A human reviews and commits manually. Do not run `git commit`, `git push`, amend, or open PRs unless the human explicitly asks.
+
+## 8. Anti-patterns (do NOT do these)
+
+- Hardcoding ports / IPs / marks / paths instead of using `constants.sh`.
+- Duplicating routing/marking logic instead of reusing `nft.sh` / `route_table_rule_mark` / `create_nft_rules`.
+- Editing the generated `main.js` by hand — edit `fe-app-netshift` TS source and rebuild.
+- Reimplementing backend logic in the UI — the UI must call `/usr/bin/netshift` / `/etc/init.d/netshift`.
+- Changing a sacred runtime value in one place while leaving the rest of the chain stale.

docs/tasks/TEMPLATE-review.md

@@ -0,0 +1,55 @@
+# Code Review — <Title> (task-NNN)
+
+> Authored by `code-reviewer`. File name: `<task-name>-review-001.md`
+> (use `-002`, `-003`, ... or append a "Re-review" section for later rounds).
+
+**Review ID:** review-001
+**Date:** <YYYY-MM-DD>
+**Scope:** <uncommitted working-tree changes | branch X vs base>
+**Reviewer:** code-reviewer agent
+
+**Files reviewed:**
+- `path/...`
+
+---
+
+## Summary
+
+<Brief, neutral assessment of what the change does and its overall quality. No
+flattery.>
+
+## Critical Issues
+
+> Must fix before merge. Architecture violations, broken runtime contract, jq
+> regex on OpenWRT, missing `exit 1` after `fatal`, hand-edited `main.js`, traffic
+> leaks, etc.
+
+### [C1] <Issue title>
+- **File:** `path/to/file` (line X)
+- **Problem:** <what is wrong and why it matters>
+- **Recommendation:** <concrete fix>
+
+## Significant Issues
+
+### [S1] <Issue title>
+- **File:** `path/to/file` (line X)
+- **Problem:** ...
+- **Recommendation:** ...
+
+## Minor Observations
+
+- **[M1]** `path/to/file`: <short note>
+
+## Test Coverage
+
+<Were the required tests/gates added and run? Backend config-gen/subscription →
+smoke test? New pure frontend logic → vitest? Was the relevant gate green? If
+frontend tests were explicitly not required, say so and state what was verified
+by reasoning + build.>
+
+## Verdict
+
+**APPROVED** | **APPROVED WITH CONDITIONS** | **REQUIRES CHANGES**
+
+<One sentence overall. If conditional, list "Conditions before merge" by issue
+ID. If changes required, list "Required before merge" by issue ID.>

docs/tasks/TEMPLATE-task.md

@@ -0,0 +1,62 @@
+# Task: <imperative title>
+
+> Authored by `architect-orchestrator`. One self-contained spec per subtask.
+> File name: `task-NNN-<kebab-slug>.md`.
+
+## Context
+
+<Narrative: what the user wants and why. Link any relevant prior tasks.>
+
+### Root cause / research basis (authoritative)
+
+<What investigation established. Cite `file:line`. State facts, not guesses.>
+
+### Operator decisions (already made — do NOT re-ask)
+
+- <Design choice the operator already approved, e.g. "Variant 2".>
+
+## Goal
+
+<One paragraph describing the desired end state.>
+
+## Scope
+
+- Layer(s): <backend ash/jq | TS/LuCI frontend | packaging/CI>.
+- Files to modify (exact paths):
+  - `path/one`
+  - `path/two`
+- Do NOT touch: <explicit out-of-scope files/areas>.
+
+## Requirements
+
+### 1. <numbered requirement>
+
+<Be specific. Include exact target `file:line` and fenced code blocks of the
+intended change where helpful.>
+
+### 2. <numbered requirement>
+
+## Architecture Notes
+
+- Applicable rules: <e.g. `docs/agent-rules/backend-shell.md` (no jq regex;
+  `fatal` needs `exit 1`)>.
+- Runtime-contract impact: <none | which ports/marks/paths and the whole-chain
+  verification required>.
+- Single-source-of-truth constraints: <constants.sh; barrel→main.*; etc.>.
+
+## Tests Required
+
+- Backend: <which `test_*` to add/extend in `tests/entrypoint.sh`, or "covered
+  by existing X">. Run the `shellcheck` and `smoke-tests` skills.
+- Frontend: <vitest `.test.js` to add, or "verify by reasoning + build">. Run
+  the `frontend-ci` skill; ensure `main.js` rebuild leaves no git diff.
+- Packaging: <smoke tests; verify ipk + apk paths>.
+
+## Definition of Done
+
+- [ ] All requirements implemented in scope; nothing out-of-scope changed.
+- [ ] Relevant gate(s) pass (shellcheck / smoke-tests / yarn ci).
+- [ ] (Frontend) `main.js` regenerated; `git diff` clean after build.
+- [ ] Runtime contract intact (or whole chain verified if changed).
+- [ ] New user-facing strings wrapped in `_()` (frontend).
+- [ ] `code-reviewer` verdict: APPROVED or APPROVED WITH CONDITIONS.

fe-app-netshift/locales/netshift.ru.po

@@ -7,8 +7,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: NETSHIFT\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-06-02 17:15+0300\n"
-"PO-Revision-Date: 2026-06-02 17:15+0300\n"
+"POT-Creation-Date: 2026-06-06 00:53+0300\n"
+"PO-Revision-Date: 2026-06-06 00:53+0300\n"
 "Last-Translator: yandexru45\n"
 "Language-Team: none\n"
 "Language: ru\n"
@@ -29,18 +29,18 @@ msgstr "✘ Отключено"
 msgid "✘ Stopped"
 msgstr "✘ Остановлен"
 
-msgid "Группировать по странам"
-msgstr ""
-
-msgid "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"
-msgstr ""
-
 msgid "Active Connections"
 msgstr "Активные соединения"
 
 msgid "Additional marking rules found"
 msgstr "Найдены дополнительные правила маркировки"
 
+msgid "Affects Cloudflare, Google, Quad9, OpenDNS, AdGuard, and Yandex public DoH servers."
+msgstr "Затрагивает публичные DoH-серверы Cloudflare, Google, Quad9, OpenDNS, AdGuard и Yandex."
+
+msgid "Allow insecure TLS for subscription fetch"
+msgstr "Разрешить небезопасный TLS при загрузке подписки"
+
 msgid "Allows access to YACD from the WAN. Make sure to open the appropriate port in your firewall."
 msgstr "Обеспечивает доступ к YACD из WAN. Убедитесь, что в брандмауэре открыт соответствующий порт."
 
@@ -56,6 +56,12 @@ msgstr "Необходимо указать хотя бы одну действ
 msgid "Available actions"
 msgstr "Доступные действия"
 
+msgid "Block direct connections to known public DNS-over-HTTPS (DoH) servers."
+msgstr "Блокирует прямые подключения к известным публичным серверам DNS-over-HTTPS (DoH)."
+
+msgid "Block DoH Servers"
+msgstr "Блокировать DoH-серверы"
+
 msgid "Bootsrap DNS"
 msgstr "Bootstrap DNS"
 
@@ -77,6 +83,9 @@ msgstr "Путь к файлу кэша не может быть пустым"
 msgid "Cannot receive checks result"
 msgstr "Не удалось получить результаты проверки"
 
+msgid "Check update"
+msgstr "Проверить обновление"
+
 msgid "Checking, please wait"
 msgstr "Проверяем, пожалуйста подождите"
 
@@ -98,11 +107,14 @@ msgstr "Закрыть"
 msgid "Community Lists"
 msgstr "Списки сообщества"
 
+msgid "Component Manager"
+msgstr "Менеджер компонентов"
+
 msgid "Config File Path"
 msgstr "Путь к файлу конфигурации"
 
 msgid "Configuration for NetShift service"
-msgstr ""
+msgstr "Конфигурация службы NetShift"
 
 msgid "Configuration Type"
 msgstr "Тип конфигурации"
@@ -116,6 +128,12 @@ msgstr "URL подключения"
 msgid "Copy"
 msgstr "Копировать"
 
+msgid "Core switch failed"
+msgstr "Не удалось переключить ядро"
+
+msgid "Core switch timed out"
+msgstr "Истекло время ожидания переключения ядра"
+
 msgid "Currently unavailable"
 msgstr "Временно недоступно"
 
@@ -126,11 +144,14 @@ msgid "Dashboard currently unavailable"
 msgstr "Дашборд сейчас недоступен"
 
 msgid "Delay in milliseconds before reloading NetShift after interface UP"
-msgstr ""
+msgstr "Задержка в миллисекундах перед перезагрузкой NetShift после поднятия интерфейса"
 
 msgid "Delay value cannot be empty"
 msgstr "Значение задержки не может быть пустым"
 
+msgid "Dev"
+msgstr "Dev"
+
 msgid "DHCP has DNS server"
 msgstr "DHCP содержит DNS сервер"
 
@@ -149,9 +170,15 @@ msgstr "Отключить QUIC протокол для улучшения со
 msgid "Disabled"
 msgstr "Отключено"
 
+msgid "Disables TLS certificate verification when downloading the subscription."
+msgstr "Отключает проверку TLS-сертификата при загрузке подписки."
+
 msgid "DNS on router"
 msgstr "DNS на роутере"
 
+msgid "DNS outbound section"
+msgstr "Секция outbound для DNS"
+
 msgid "DNS over HTTPS (DoH)"
 msgstr "DNS через HTTPS (DoH)"
 
@@ -194,6 +221,9 @@ msgstr "Скачивать списки через выбранную секци
 msgid "Downloading all lists via specific Proxy/VPN"
 msgstr "Загрузка всех списков через указанный прокси/VPN"
 
+msgid "Drop subscription servers whose name contains any of these keywords (case-insensitive)."
+msgstr "Исключать серверы подписки, имя которых содержит любое из этих ключевых слов (без учёта регистра)."
+
 msgid "Dynamic List"
 msgstr "Динамический список"
 
@@ -206,6 +236,12 @@ msgstr "Включить встроенный DNS-резолвер для дом
 msgid "Enable DNS resolve to get real IP when routing"
 msgstr "Разрешать домены в реальные IP-адреса перед маршрутизацией в outbound"
 
+msgid "Enable IPv6 Support"
+msgstr "Включить поддержку IPv6"
+
+msgid "Enable IPv6 TProxy routing, IPv6 DNS inbound, and IPv6 FakeIP support."
+msgstr "Включить маршрутизацию TProxy по IPv6, входящий DNS по IPv6 и поддержку FakeIP для IPv6."
+
 msgid "Enable Mixed Proxy"
 msgstr "Включить смешанный прокси"
 
@@ -234,22 +270,22 @@ msgid "Enter subnets in CIDR notation (e.g. 103.21.244.0/22) or single IP addres
 msgstr "Введите подсети в нотации CIDR (например, 103.21.244.0/22) или отдельные IP-адреса"
 
 msgid "Enter the subscription URL to fetch proxy configurations from your provider"
-msgstr ""
+msgstr "Введите URL подписки для получения конфигураций прокси от вашего провайдера"
 
 msgid "Every 1 minute"
 msgstr "Каждую минуту"
 
 msgid "Every 12 hours"
-msgstr ""
+msgstr "Каждые 12 часов"
 
 msgid "Every 3 hours"
-msgstr ""
+msgstr "Каждые 3 часа"
 
 msgid "Every 3 minutes"
 msgstr "Каждые 3 минуты"
 
 msgid "Every 30 minutes"
-msgstr ""
+msgstr "Каждые 30 минут"
 
 msgid "Every 30 seconds"
 msgstr "Каждые 30 секунд"
@@ -258,13 +294,13 @@ msgid "Every 5 minutes"
 msgstr "Каждые 5 минут"
 
 msgid "Every 6 hours"
-msgstr ""
+msgstr "Каждые 6 часов"
 
 msgid "Every day"
-msgstr ""
+msgstr "Каждый день"
 
 msgid "Every hour"
-msgstr ""
+msgstr "Каждый час"
 
 msgid "Exclude NTP"
 msgstr "Исключить NTP"
@@ -272,6 +308,9 @@ msgstr "Исключить NTP"
 msgid "Exclude NTP protocol traffic from the tunnel to prevent it from being routed through the proxy or VPN"
 msgstr "Исключите трафик протокола NTP из туннеля, чтобы предотвратить его маршрутизацию через прокси-сервер или VPN."
 
+msgid "Exclude servers by keyword"
+msgstr "Исключать серверы по ключевому слову"
+
 msgid "Failed to copy!"
 msgstr "Не удалось скопировать!"
 
@@ -290,17 +329,23 @@ msgstr "Получить глобальную проверку"
 msgid "Global check"
 msgstr "Глобальная проверка"
 
+msgid "Global Proxy"
+msgstr "Глобальный прокси"
+
 msgid "How often to automatically update the subscription"
-msgstr ""
+msgstr "Как часто автоматически обновлять подписку"
 
 msgid "HTTP error"
 msgstr "Ошибка HTTP"
 
-msgid "Install extended"
-msgstr "Установить extended"
+msgid "Include servers by keyword"
+msgstr "Включать серверы по ключевому слову"
 
-msgid "Install stable"
-msgstr "Установить stable"
+msgid "Install %s"
+msgstr "Установить %s"
+
+msgid "Installed version is newer than release"
+msgstr "Установленная версия новее релиза"
 
 msgid "Interface Monitoring"
 msgstr "Мониторинг интерфейса"
@@ -311,14 +356,14 @@ msgstr "Задержка при мониторинге интерфейсов"
 msgid "Interface monitoring for Bad WAN"
 msgstr "Мониторинг интерфейса для Bad WAN"
 
-msgid "Invalid DNS server format. Examples: 8.8.8.8 or dns.example.com or dns.example.com/nicedns for DoH"
-msgstr "Неверный формат DNS-сервера. Примеры: 8.8.8.8, dns.example.com или dns.example.com/nicedns для DoH"
+msgid "Invalid DNS server format. Examples: 8.8.8.8, [::1], dns.example.com, or dns.example.com/dns-query for DoH"
+msgstr "Неверный формат DNS-сервера. Примеры: 8.8.8.8, [::1], dns.example.com или dns.example.com/dns-query для DoH"
 
 msgid "Invalid domain address"
 msgstr "Неверный домен"
 
-msgid "Invalid format. Use X.X.X.X or X.X.X.X/Y"
-msgstr "Неверный формат. Используйте X.X.X.X или X.X.X.X/Y"
+msgid "Invalid format. Use X.X.X.X/Y or IPv6/Y"
+msgstr "Неверный формат. Используйте X.X.X.X/Y или IPv6/Y"
 
 msgid "Invalid HY2 URL: insecure must be 0 or 1"
 msgstr "Неверный URL Hysteria2: параметр insecure должен быть 0 или 1"
@@ -362,6 +407,9 @@ msgstr "Неверный URL Hysteria2: неподдерживаемый тип
 msgid "Invalid IP address"
 msgstr "Неверный IP-адрес"
 
+msgid "Invalid IPv6 address"
+msgstr "Неверный IPv6-адрес"
+
 msgid "Invalid JSON format"
 msgstr "Неверный формат JSON"
 
@@ -440,15 +488,48 @@ msgstr "Неверный формат URL"
 msgid "Invalid VLESS URL: parsing failed"
 msgstr "Неверный URL VLESS: ошибка разбора"
 
+msgid "Invalid VMess URL: invalid port"
+msgstr "Неверный URL VMess: недопустимый порт"
+
+msgid "Invalid VMess URL: malformed base64"
+msgstr "Неверный URL VMess: некорректный base64"
+
+msgid "Invalid VMess URL: malformed JSON"
+msgstr "Неверный URL VMess: некорректный JSON"
+
+msgid "Invalid VMess URL: missing address"
+msgstr "Неверный URL VMess: отсутствует адрес"
+
+msgid "Invalid VMess URL: missing id"
+msgstr "Неверный URL VMess: отсутствует id"
+
+msgid "Invalid VMess URL: must not contain spaces"
+msgstr "Неверный URL VMess: не должен содержать пробелы"
+
+msgid "Invalid VMess URL: must start with vmess://"
+msgstr "Неверный URL VMess: должен начинаться с vmess://"
+
 msgid "IP address 0.0.0.0 is not allowed"
 msgstr "IP-адрес 0.0.0.0 не допускается"
 
+msgid "IPv6 CIDR must be between 0 and 128"
+msgstr "IPv6 CIDR должен быть от 0 до 128"
+
 msgid "Issues detected"
 msgstr "Обнаружены проблемы"
 
+msgid "Keep only subscription servers whose name contains at least one of these keywords (case-insensitive). Leave empty to keep all."
+msgstr "Оставлять только серверы подписки, имя которых содержит хотя бы одно из этих ключевых слов (без учёта регистра). Оставьте пустым, чтобы оставить все."
+
 msgid "Latest"
 msgstr "Последняя"
 
+msgid "Latest version is installed"
+msgstr "Установлена последняя версия"
+
+msgid "Latest version is unknown"
+msgstr "Последняя версия неизвестна"
+
 msgid "List Update Frequency"
 msgstr "Частота обновления списков"
 
@@ -464,6 +545,9 @@ msgstr "Уровень логов"
 msgid "Main DNS"
 msgstr "Основной DNS"
 
+msgid "Main DNS via outbound"
+msgstr "Основной DNS через outbound"
+
 msgid "Memory Usage"
 msgstr "Использование памяти"
 
@@ -477,13 +561,16 @@ msgid "Must be a number in the range of 50 - 1000"
 msgstr "Должно быть числом от 50 до 1000"
 
 msgid "NetShift"
-msgstr ""
+msgstr "NetShift"
 
 msgid "NetShift Settings"
-msgstr ""
+msgstr "Настройки NetShift"
+
+msgid "NetShift updated, version:"
+msgstr "NetShift обновлён, версия:"
 
 msgid "NetShift will not modify your DHCP configuration"
-msgstr ""
+msgstr "NetShift не будет изменять вашу конфигурацию DHCP"
 
 msgid "Network Interface"
 msgstr "Сетевой интерфейс"
@@ -494,12 +581,21 @@ msgstr "Другие правила маркировки не найдены"
 msgid "Not implement yet"
 msgstr "Ещё не реализовано"
 
+msgid "Not installed"
+msgstr "Не установлено"
+
 msgid "Not responding"
 msgstr "Не отвечает"
 
 msgid "Not running"
 msgstr "Не запущено"
 
+msgid "Note: if your upstream DNS type is set to 'DoH', enable this only after switching to UDP or DoT."
+msgstr "Примечание: если тип вышестоящего DNS установлен в «DoH», включайте это только после переключения на UDP или DoT."
+
+msgid "Only one section can be global at a time."
+msgstr "Только одна секция может быть глобальной одновременно."
+
 msgid "Operation timed out"
 msgstr "Время ожидания истекло"
 
@@ -552,7 +648,13 @@ msgid "Resolve real IP for routing"
 msgstr "Разрешение реальных IP-адресов"
 
 msgid "Restart NetShift"
-msgstr ""
+msgstr "Перезапустить NetShift"
+
+msgid "Route all unmatched traffic through this section's outbound."
+msgstr "Направлять весь несовпавший трафик через outbound этой секции."
+
+msgid "Route main DNS through proxy/VPN"
+msgstr "Основной DNS через прокси/VPN"
 
 msgid "Router DNS is not routed through sing-box"
 msgstr "DNS роутера не проходит через sing-box"
@@ -569,9 +671,6 @@ msgstr "Счётчики правил mangle"
 msgid "Rules mangle exist"
 msgstr "Правила mangle существуют"
 
-msgid "Rules mangle output counters"
-msgstr "Счётчики правил mangle output"
-
 msgid "Rules mangle output exist"
 msgstr "Правила mangle output существуют"
 
@@ -647,6 +746,12 @@ msgstr "Selector"
 msgid "Selector Proxy Links"
 msgstr "Ссылки прокси для Selector"
 
+msgid "Self-update failed"
+msgstr "Не удалось обновить"
+
+msgid "Send upstream DNS queries through a proxy/VPN outbound instead of directly. Bootstrap DNS always stays direct."
+msgstr "Отправлять запросы к основному DNS через outbound прокси/VPN вместо прямого подключения. Bootstrap DNS всегда остаётся прямым."
+
 msgid "Services info"
 msgstr "Информация о сервисах"
 
@@ -699,23 +804,32 @@ msgid "Specify the path to the list file located on the router filesystem"
 msgstr "Укажите путь к файлу списка, расположенному в файловой системе маршрутизатора."
 
 msgid "Start NetShift"
-msgstr ""
+msgstr "Запустить NetShift"
 
 msgid "Stop NetShift"
-msgstr ""
+msgstr "Остановить NetShift"
 
 msgid "Subscription"
-msgstr ""
+msgstr "Подписка"
 
 msgid "Subscription Update Interval"
-msgstr ""
+msgstr "Интервал обновления подписки"
 
 msgid "Subscription URL"
-msgstr ""
+msgstr "URL подписки"
 
 msgid "Successfully copied!"
 msgstr "Успешно скопировано!"
 
+msgid "Switch to extended"
+msgstr "Переключить на extended"
+
+msgid "Switch to stable"
+msgstr "Переключить на stable"
+
+msgid "Switching sing-box core, this may take a few minutes…"
+msgstr "Переключение ядра sing-box, это может занять несколько минут…"
+
 msgid "System info"
 msgstr "Системная информация"
 
@@ -743,6 +857,12 @@ msgstr "Максимально допустимая разница во врем
 msgid "The URL used to test server connectivity"
 msgstr "URL-адрес, используемый для проверки подключения к серверу"
 
+msgid "This is a security trade-off: an attacker could intercept the fetch."
+msgstr "Это компромисс в безопасности: злоумышленник может перехватить загрузку."
+
+msgid "This prevents applications from bypassing the router's DNS filtering by using their own encrypted DNS."
+msgstr "Это не позволяет приложениям обходить DNS-фильтрацию роутера за счёт использования собственного шифрованного DNS."
+
 msgid "Time in seconds for DNS record caching (default: 60)"
 msgstr "Время в секундах для кэширования DNS записей (по умолчанию: 60)"
 
@@ -773,11 +893,23 @@ msgstr "неизвестно"
 msgid "Unknown error"
 msgstr "Неизвестная ошибка"
 
+msgid "Update"
+msgstr "Обновить"
+
+msgid "Update is available"
+msgstr "Доступно обновление"
+
+msgid "Update NetShift"
+msgstr "Обновить NetShift"
+
+msgid "Updating NetShift, this may take a few minutes; the page will reload…"
+msgstr "Обновление NetShift, это может занять несколько минут; страница перезагрузится…"
+
 msgid "Uplink"
 msgstr "Исходящий"
 
-msgid "URL must start with vless://, ss://, trojan://, socks4/5://, or hysteria2://hy2://"
-msgstr "URL должен начинаться с vless://, ss://, trojan://, socks4/5:// или hysteria2:// hy2://"
+msgid "URL must start with vless://, vmess://, ss://, trojan://, socks4/5://, or hysteria2://hy2://"
+msgstr "URL должен начинаться с vless://, vmess://, ss://, trojan://, socks4/5:// или hysteria2:// hy2://"
 
 msgid "URL must use one of the following protocols:"
 msgstr "URL должен использовать один из следующих протоколов:"
@@ -797,6 +929,15 @@ msgstr "URLTest ссылка для проверки"
 msgid "URLTest Tolerance"
 msgstr "URLTest допустимое отклонение"
 
+msgid "Use only for IP-host panels that serve an invalid or self-signed certificate."
+msgstr "Используйте только для панелей с IP-адресом, у которых недействительный или самоподписанный сертификат."
+
+msgid "Use this only when the router has working IPv6 connectivity."
+msgstr "Используйте это только если на роутере есть рабочее подключение по IPv6."
+
+msgid "Use with Exclusion sections to route specific domains directly."
+msgstr "Используйте вместе с секциями исключений для прямой маршрутизации определённых доменов."
+
 msgid "User Domain List Type"
 msgstr "Тип пользовательского списка доменов"
 
@@ -821,14 +962,17 @@ msgstr "Валидно"
 msgid "Validation errors:"
 msgstr "Ошибки валидации:"
 
+msgid "Version"
+msgstr "Версия"
+
 msgid "View logs"
 msgstr "Посмотреть логи"
 
 msgid "Visit Wiki"
 msgstr "Перейти в wiki"
 
-msgid "vless://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links"
-msgstr ""
+msgid "vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links"
+msgstr "ссылки vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2://"
 
 msgid "Warning: %s cannot be used together with %s. Previous selections have been removed."
 msgstr "Предупреждение: %s нельзя использовать вместе с %s. Предыдущие варианты были удалены."
@@ -836,8 +980,20 @@ msgstr "Предупреждение: %s нельзя использовать
 msgid "Warning: Russia inside can only be used with %s. %s already in Russia inside and have been removed from selection."
 msgstr "Предупреждение: Russia inside может быть использован только с %s. %s уже есть в Russia inside и будет удален из выбранных."
 
+msgid "When enabled, traffic not matching any other section's lists will go through this proxy."
+msgstr "Когда включено, трафик, не совпадающий со списками других секций, будет идти через этот прокси."
+
+msgid "Which proxy/VPN section carries the DNS. Leave unset to use the first configured outbound."
+msgstr "Какая секция прокси/VPN обслуживает DNS. Оставьте пустым, чтобы использовать первый настроенный outbound."
+
 msgid "YACD Secret Key"
 msgstr "Секретный ключ YACD"
 
 msgid "You can select Output Network Interface, by default autodetect"
 msgstr "Вы можете выбрать выходной сетевой интерфейс, по умолчанию он определяется автоматически."
+
+msgid "Группировать по странам"
+msgstr "Группировать по странам"
+
+msgid "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"
+msgstr "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"

fe-app-netshift/src/constants.ts

@@ -83,6 +83,9 @@ export const DNS_SERVER_OPTIONS = {
   'unfiltered.adguard-dns.com':
     'unfiltered.adguard-dns.com (AdGuard Unfiltered)',
   'family.adguard-dns.com': 'family.adguard-dns.com (AdGuard Family)',
+  '2001:4860:4860::8888': '2001:4860:4860::8888 (Google IPv6)',
+  '2606:4700:4700::1111': '2606:4700:4700::1111 (Cloudflare IPv6)',
+  '2620:fe::fe': '2620:fe::fe (Quad9 IPv6)',
 };
 export const BOOTSTRAP_DNS_SERVER_OPTIONS = {
   '77.88.8.8': '77.88.8.8 (Yandex DNS)',
@@ -93,6 +96,8 @@ export const BOOTSTRAP_DNS_SERVER_OPTIONS = {
   '8.8.4.4': '8.8.4.4 (Google DNS)',
   '9.9.9.9': '9.9.9.9 (Quad9 DNS)',
   '9.9.9.11': '9.9.9.11 (Quad9 DNS)',
+  '2001:4860:4860::8888': '2001:4860:4860::8888 (Google DNS IPv6)',
+  '2606:4700:4700::1111': '2606:4700:4700::1111 (Cloudflare DNS IPv6)',
 };
 
 export const DIAGNOSTICS_UPDATE_INTERVAL = 10000; // 10 seconds

fe-app-netshift/src/netshift/methods/shell/index.ts

@@ -1,12 +1,14 @@
 import { callBaseMethod } from './callBaseMethod';
 import { ClashAPI, NetShift } from '../../types';
 import { executeShellCommand } from '../../../helpers';
-
-interface SingBoxComponentActionResult {
-  success: boolean;
-  version?: string;
-  message?: string;
-}
+import {
+  ComponentActionStartResponse,
+  ComponentActionStatus,
+  SingBoxComponentActionResult,
+  parseComponentActionStatus,
+  pollSingBoxComponentAction,
+} from './pollSingBoxComponentAction';
+import { parseComponentCheckUpdate } from './parseComponentCheckUpdate';
 
 export const NetShiftShellMethods = {
   checkDNSAvailable: async () =>
@@ -96,6 +98,90 @@ export const NetShiftShellMethods = {
   singBoxComponentAction: async (
     action: 'install_extended' | 'install_stable' | 'check_update',
   ): Promise<SingBoxComponentActionResult> => {
+    // `check_update` is a quick single call — not subject to the rpcd 30s wall —
+    // so keep it on the SYNCHRONOUS `component_action` path (unchanged shape).
+    if (action === 'check_update') {
+      const response = await executeShellCommand({
+        command: '/usr/bin/netshift',
+        args: ['component_action', 'sing_box', action],
+        timeout: 600000,
+      });
+
+      if (response.stdout) {
+        try {
+          const parsed = JSON.parse(
+            response.stdout,
+          ) as SingBoxComponentActionResult;
+
+          return {
+            success: Boolean(parsed.success),
+            version: parsed.version,
+            message: parsed.message,
+          };
+        } catch (_e) {
+          return {
+            success: false,
+            message: response.stdout,
+          };
+        }
+      }
+
+      return {
+        success: false,
+        message: response.stderr || '',
+      };
+    }
+
+    // Install actions can take minutes — drive the async backend contract:
+    // start the job, then poll `component_action_status` with short execs so
+    // rpcd never kills a single long-running call.
+    const startResponse = await executeShellCommand({
+      command: '/usr/bin/netshift',
+      args: ['component_action_async', 'sing_box', action],
+    });
+
+    let start: ComponentActionStartResponse | null = null;
+
+    if (startResponse.stdout) {
+      try {
+        start = JSON.parse(
+          startResponse.stdout,
+        ) as ComponentActionStartResponse;
+      } catch (_e) {
+        start = null;
+      }
+    }
+
+    if (!start || start.success !== true || !start.job_id) {
+      return {
+        success: false,
+        message:
+          start?.message || startResponse.stderr || _('Core switch failed'),
+      };
+    }
+
+    const jobId = start.job_id;
+
+    return pollSingBoxComponentAction(async () => {
+      const statusResponse = await executeShellCommand({
+        command: '/usr/bin/netshift',
+        args: ['component_action_status', jobId],
+      });
+
+      if (!statusResponse.stdout) {
+        return null;
+      }
+
+      return parseComponentActionStatus(statusResponse.stdout);
+    });
+  },
+  // Sing-box update checks (sync) — STABLE task-017 contract:
+  //   component_action sing_box check_update        (extended)
+  //   component_action sing_box check_update_stable (stock)
+  // → {success, current_version, latest_version, status}.
+  singBoxCheckUpdate: async (
+    action: 'check_update' | 'check_update_stable',
+  ): Promise<NetShift.ComponentCheckUpdateResult> => {
     const response = await executeShellCommand({
       command: '/usr/bin/netshift',
       args: ['component_action', 'sing_box', action],
@@ -103,22 +189,7 @@ export const NetShiftShellMethods = {
     });
 
     if (response.stdout) {
-      try {
-        const parsed = JSON.parse(
-          response.stdout,
-        ) as SingBoxComponentActionResult;
-
-        return {
-          success: Boolean(parsed.success),
-          version: parsed.version,
-          message: parsed.message,
-        };
-      } catch (_e) {
-        return {
-          success: false,
-          message: response.stdout,
-        };
-      }
+      return parseComponentCheckUpdate(response.stdout);
     }
 
     return {
@@ -126,4 +197,63 @@ export const NetShiftShellMethods = {
       message: response.stderr || '',
     };
   },
+  // NetShift self-update (async) — STABLE task-017 contract:
+  // component_action_async netshift self_update + component_action_status <job>.
+  // Reuses the component-agnostic poll. Because the package install swaps
+  // /usr/bin/netshift mid-job, status polls can transiently fail (rpcd / binary
+  // swap); once the job has STARTED we treat such failures leniently — keep
+  // polling (return a synthetic running status) instead of aborting hard, so a
+  // successful self-update is not misreported as a failure. The UI reloads the
+  // page on success.
+  netshiftSelfUpdate: async (): Promise<SingBoxComponentActionResult> => {
+    const startResponse = await executeShellCommand({
+      command: '/usr/bin/netshift',
+      args: ['component_action_async', 'netshift', 'self_update'],
+    });
+
+    let start: ComponentActionStartResponse | null = null;
+
+    if (startResponse.stdout) {
+      try {
+        start = JSON.parse(
+          startResponse.stdout,
+        ) as ComponentActionStartResponse;
+      } catch (_e) {
+        start = null;
+      }
+    }
+
+    if (!start || start.success !== true || !start.job_id) {
+      return {
+        success: false,
+        message:
+          start?.message || startResponse.stderr || _('Self-update failed'),
+      };
+    }
+
+    const jobId = start.job_id;
+
+    return pollSingBoxComponentAction(async () => {
+      // Lenient mid-job polling: any exec/parse error AFTER a successful start
+      // is reported as "still running" so the binary swap doesn't end the loop
+      // prematurely. The MAX_POLLS backstop still bounds the loop.
+      try {
+        const statusResponse = await executeShellCommand({
+          command: '/usr/bin/netshift',
+          args: ['component_action_status', jobId],
+        });
+
+        if (!statusResponse.stdout) {
+          return { running: true } as ComponentActionStatus;
+        }
+
+        return (
+          parseComponentActionStatus(statusResponse.stdout) ??
+          ({ running: true } as ComponentActionStatus)
+        );
+      } catch (_e) {
+        return { running: true } as ComponentActionStatus;
+      }
+    });
+  },
 };

fe-app-netshift/src/netshift/methods/shell/parseComponentCheckUpdate.ts

@@ -0,0 +1,58 @@
+import { NetShift } from '../../types';
+
+const VALID_STATUSES: NetShift.ComponentUpdateStatus[] = [
+  'latest',
+  'outdated',
+  'dev',
+  'not_installed',
+];
+
+function normalizeStatus(
+  status: unknown,
+): NetShift.ComponentUpdateStatus | undefined {
+  if (
+    typeof status === 'string' &&
+    (VALID_STATUSES as string[]).includes(status)
+  ) {
+    return status as NetShift.ComponentUpdateStatus;
+  }
+
+  return undefined;
+}
+
+/**
+ * Parse the STABLE JSON echoed by the sync update-check actions
+ * (`component_action sing_box check_update` /
+ * `component_action sing_box check_update_stable`):
+ * `{success, current_version, latest_version, status}`.
+ *
+ * Pure (types-only import) so it is unit-testable without dragging in the
+ * helpers barrel (which pulls TabService → MutationObserver and crashes the
+ * node test env at collect time).
+ */
+export function parseComponentCheckUpdate(
+  stdout: string,
+): NetShift.ComponentCheckUpdateResult {
+  try {
+    const parsed = JSON.parse(stdout) as Record<string, unknown>;
+
+    return {
+      success: Boolean(parsed.success),
+      current_version:
+        typeof parsed.current_version === 'string'
+          ? parsed.current_version
+          : undefined,
+      latest_version:
+        typeof parsed.latest_version === 'string'
+          ? parsed.latest_version
+          : undefined,
+      status: normalizeStatus(parsed.status),
+      message: typeof parsed.message === 'string' ? parsed.message : undefined,
+    };
+  } catch (_e) {
+    return {
+      success: false,
+      message: stdout,
+    };
+  }
+}

fe-app-netshift/src/netshift/methods/shell/pollSingBoxComponentAction.ts

@@ -0,0 +1,84 @@
+import { sleep } from './sleep';
+
+export interface SingBoxComponentActionResult {
+  success: boolean;
+  version?: string;
+  message?: string;
+}
+
+// Shape echoed by `component_action_async sing_box <action>` on start.
+export interface ComponentActionStartResponse {
+  success?: boolean;
+  job_id?: string;
+  message?: string;
+}
+
+// Shape echoed by `component_action_status <job_id>` (task-007/009 contract).
+export interface ComponentActionStatus {
+  success?: boolean;
+  running?: boolean;
+  component?: string;
+  action?: string;
+  message?: string;
+  pid?: number | null;
+  started_at?: number;
+  updated_at?: number;
+  exit_code?: number | null;
+  version?: string;
+  latest_version?: string;
+}
+
+// ~2s between polls; ~150 polls ≈ 5 min backstop against a wedged job.
+export const POLL_INTERVAL_MS = 2000;
+export const MAX_POLLS = 150;
+
+export function parseComponentActionStatus(
+  stdout: string,
+): ComponentActionStatus | null {
+  try {
+    return JSON.parse(stdout) as ComponentActionStatus;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Pure poll loop for the async core switch. Each `fetchStatus` call is a tiny,
+ * individual `component_action_status` exec (well under the rpcd 30s wall); the
+ * loop runs until the job is no longer running (a parse failure or
+ * `running === false` is terminal). `sleepFn` is injected so tests can avoid
+ * real 2s waits.
+ */
+export async function pollSingBoxComponentAction(
+  fetchStatus: () => Promise<ComponentActionStatus | null>,
+  sleepFn: (ms: number) => Promise<void> = sleep,
+  intervalMs: number = POLL_INTERVAL_MS,
+  maxPolls: number = MAX_POLLS,
+): Promise<SingBoxComponentActionResult> {
+  for (let poll = 0; poll < maxPolls; poll += 1) {
+    const status = await fetchStatus();
+
+    // A parse failure (null) is terminal — we cannot keep polling blindly.
+    if (!status) {
+      return {
+        success: false,
+        message: _('Core switch failed'),
+      };
+    }
+
+    if (status.running !== true) {
+      return {
+        success: Boolean(status.success),
+        version: status.version,
+        message: status.message,
+      };
+    }
+
+    await sleepFn(intervalMs);
+  }
+
+  return {
+    success: false,
+    message: _('Core switch timed out'),
+  };
+}

fe-app-netshift/src/netshift/methods/shell/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

fe-app-netshift/src/netshift/methods/shell/tests/parseComponentCheckUpdate.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { parseComponentCheckUpdate } from '../parseComponentCheckUpdate';
+
+describe('parseComponentCheckUpdate', () => {
+  it('parses the STABLE check-update JSON', () => {
+    const result = parseComponentCheckUpdate(
+      JSON.stringify({
+        success: true,
+        current_version: '1.12.0',
+        latest_version: '1.12.9',
+        status: 'outdated',
+      }),
+    );
+
+    expect(result).toEqual({
+      success: true,
+      current_version: '1.12.0',
+      latest_version: '1.12.9',
+      status: 'outdated',
+      message: undefined,
+    });
+  });
+
+  it.each(['latest', 'outdated', 'dev', 'not_installed'])(
+    'accepts the valid status %s',
+    (status) => {
+      const result = parseComponentCheckUpdate(
+        JSON.stringify({ success: true, status }),
+      );
+
+      expect(result.status).toBe(status);
+    },
+  );
+
+  it('drops an unknown status to undefined', () => {
+    const result = parseComponentCheckUpdate(
+      JSON.stringify({ success: true, status: 'weird' }),
+    );
+
+    expect(result.status).toBeUndefined();
+  });
+
+  it('returns success:false with the raw stdout on invalid JSON', () => {
+    const result = parseComponentCheckUpdate('not json');
+
+    expect(result).toEqual({ success: false, message: 'not json' });
+  });
+
+  it('coerces a missing success to false', () => {
+    const result = parseComponentCheckUpdate(JSON.stringify({}));
+
+    expect(result.success).toBe(false);
+  });
+});

fe-app-netshift/src/netshift/methods/shell/tests/pollSingBoxComponentAction.test.js

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from 'vitest';
+import { pollSingBoxComponentAction } from '../pollSingBoxComponentAction';
+
+// No-op sleep so polls resolve instantly (no real 2s waits in tests).
+const noSleep = () => Promise.resolve();
+
+// Build a fetchStatus callback that returns the queued statuses in order,
+// then keeps returning the last one.
+function makeFetchStatus(statuses) {
+  let index = 0;
+
+  return vi.fn(async () => {
+    const status = statuses[Math.min(index, statuses.length - 1)];
+    index += 1;
+
+    return status;
+  });
+}
+
+describe('pollSingBoxComponentAction', () => {
+  it('resolves success with version after N running polls then terminal', async () => {
+    const fetchStatus = makeFetchStatus([
+      { running: true, success: true, exit_code: null },
+      { running: true, success: true, exit_code: null },
+      {
+        running: false,
+        success: true,
+        version: '1.12.4',
+        message: 'Core switched',
+        exit_code: 0,
+      },
+    ]);
+
+    const result = await pollSingBoxComponentAction(fetchStatus, noSleep);
+
+    expect(result).toEqual({
+      success: true,
+      version: '1.12.4',
+      message: 'Core switched',
+    });
+    // 3 status reads (2 running + 1 terminal).
+    expect(fetchStatus).toHaveBeenCalledTimes(3);
+  });
+
+  it('surfaces the failure message on terminal success:false', async () => {
+    const fetchStatus = makeFetchStatus([
+      { running: true, success: true },
+      {
+        running: false,
+        success: false,
+        message: 'core switch aborted (existing sing-box left intact)',
+        exit_code: 1,
+      },
+    ]);
+
+    const result = await pollSingBoxComponentAction(fetchStatus, noSleep);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe(
+      'core switch aborted (existing sing-box left intact)',
+    );
+  });
+
+  it('treats a parse failure (null status) as terminal failure', async () => {
+    const fetchStatus = makeFetchStatus([
+      { running: true, success: true },
+      null,
+    ]);
+
+    const result = await pollSingBoxComponentAction(fetchStatus, noSleep);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe('Core switch failed');
+  });
+
+  it('returns timeout when the safety cap is exceeded', async () => {
+    // Always running → never terminal.
+    const fetchStatus = vi.fn(async () => ({ running: true, success: true }));
+
+    const result = await pollSingBoxComponentAction(fetchStatus, noSleep, 0, 5);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe('Core switch timed out');
+    expect(fetchStatus).toHaveBeenCalledTimes(5);
+  });
+
+  it('returns immediately on a terminal-first status', async () => {
+    const fetchStatus = makeFetchStatus([
+      {
+        running: false,
+        success: true,
+        version: '1.13.0',
+        message: 'done',
+      },
+    ]);
+
+    const result = await pollSingBoxComponentAction(fetchStatus, noSleep);
+
+    expect(result).toEqual({
+      success: true,
+      version: '1.13.0',
+      message: 'done',
+    });
+    expect(fetchStatus).toHaveBeenCalledTimes(1);
+  });
+});

fe-app-netshift/src/netshift/methods/shell/tests/singBoxComponentAction.test.js

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// `methods/shell/index.ts` (and its `callBaseMethod` import) pull in the
+// `../../../helpers` barrel, which transitively loads `withTimeout` →
+// `../netshift` → `TabService`, whose constructor calls `new MutationObserver`
+// at module-init time. In the node test env that throws
+// "MutationObserver is not defined" at COLLECT time. Mocking the helpers barrel
+// here short-circuits that chain so we can import and exercise the REAL
+// `singBoxComponentAction` method while controlling its `executeShellCommand`.
+const executeShellCommand = vi.fn();
+
+vi.mock('../../../../helpers', () => ({
+  executeShellCommand: (...args) => executeShellCommand(...args),
+}));
+
+// Avoid pulling the real `callBaseMethod` (also imports the helpers barrel and
+// the LuCI types); the start-failure path under test never reaches it.
+vi.mock('../../callBaseMethod', () => ({
+  callBaseMethod: vi.fn(),
+}));
+
+const { NetShiftShellMethods } = await import('../index');
+
+afterEach(() => {
+  executeShellCommand.mockReset();
+});
+
+describe('singBoxComponentAction (start-failure path)', () => {
+  it('fails fast on start success:false WITHOUT entering the poll loop', async () => {
+    executeShellCommand.mockResolvedValueOnce({
+      stdout: JSON.stringify({
+        success: false,
+        message: 'binary updater is busy',
+      }),
+      stderr: '',
+    });
+
+    const result =
+      await NetShiftShellMethods.singBoxComponentAction('install_extended');
+
+    expect(result).toEqual({
+      success: false,
+      message: 'binary updater is busy',
+    });
+    // Only the async-start call ran; no `component_action_status` polls.
+    expect(executeShellCommand).toHaveBeenCalledTimes(1);
+    expect(executeShellCommand).toHaveBeenCalledWith({
+      command: '/usr/bin/netshift',
+      args: ['component_action_async', 'sing_box', 'install_extended'],
+    });
+  });
+
+  it('fails fast when the start response has no job_id', async () => {
+    executeShellCommand.mockResolvedValueOnce({
+      stdout: JSON.stringify({ success: true }),
+      stderr: '',
+    });
+
+    const result =
+      await NetShiftShellMethods.singBoxComponentAction('install_stable');
+
+    expect(result.success).toBe(false);
+    expect(executeShellCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it('surfaces stderr / generic message when start output is unparseable', async () => {
+    executeShellCommand.mockResolvedValueOnce({
+      stdout: 'not json',
+      stderr: 'boom',
+    });
+
+    const result =
+      await NetShiftShellMethods.singBoxComponentAction('install_extended');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe('boom');
+    expect(executeShellCommand).toHaveBeenCalledTimes(1);
+  });
+});

fe-app-netshift/src/netshift/services/store.service.ts

@@ -1,5 +1,11 @@
 import { NetShift } from '../types';
 import { initialDiagnosticStore } from '../tabs/diagnostic/diagnostic.store';
+import { initialManagerStore } from '../tabs/manager/manager.store';
+import type { ManagerComponentKey } from '../tabs/manager/cards';
+
+// Single source of truth for the component key union lives in `tabs/manager/cards`;
+// re-export it here so store consumers keep their existing import path.
+export type { ManagerComponentKey };
 
 function jsonStableStringify<T, V>(obj: T): string {
   return JSON.stringify(obj, (_, value) => {
@@ -180,7 +186,6 @@ export interface StoreType {
     globalCheck: { loading: boolean };
     viewLogs: { loading: boolean };
     showSingBoxConfig: { loading: boolean };
-    singBoxInstall: { loading: boolean };
   };
   diagnosticsSystemInfo: {
     loading: boolean;
@@ -192,6 +197,21 @@ export interface StoreType {
     device_model: string;
     sing_box_extended: 0 | 1;
   };
+  managerActions: {
+    netshiftCheck: { loading: boolean };
+    netshiftUpdate: { loading: boolean };
+    singBoxStockCheck: { loading: boolean };
+    singBoxStockAction: { loading: boolean };
+    singBoxExtendedCheck: { loading: boolean };
+    singBoxExtendedAction: { loading: boolean };
+  };
+  managerChecks: Record<
+    ManagerComponentKey,
+    {
+      status: NetShift.ComponentUpdateStatus | null;
+      latest_version: string;
+    }
+  >;
 }
 
 const initialStore: StoreType = {
@@ -226,6 +246,7 @@ const initialStore: StoreType = {
     data: [],
   },
   ...initialDiagnosticStore,
+  ...initialManagerStore,
 };
 
 export const store = new StoreService<StoreType>(initialStore);

fe-app-netshift/src/netshift/tabs/diagnostic/checks/runDnsCheck.ts

@@ -72,6 +72,17 @@ export async function runDnsCheck() {
         key: _('Main DNS'),
         value: `${data.dns_server} [${data.dns_type}]`,
       },
+      ...insertIf<IDiagnosticsChecksItem>(
+        typeof data.dns_via_outbound_tag === 'string' &&
+          data.dns_via_outbound_tag.length > 0,
+        [
+          {
+            state: 'success',
+            key: _('Main DNS via outbound'),
+            value: data.dns_via_outbound_tag ?? '',
+          },
+        ],
+      ),
       {
         state: data.dns_on_router ? 'success' : 'error',
         key: _('DNS on router'),

fe-app-netshift/src/netshift/tabs/diagnostic/checks/runNftCheck.ts

@@ -40,7 +40,6 @@ export async function runNftCheck() {
     Boolean(data.rules_mangle_exist) &&
     Boolean(data.rules_mangle_counters) &&
     Boolean(data.rules_mangle_output_exist) &&
-    Boolean(data.rules_mangle_output_counters) &&
     Boolean(data.rules_proxy_exist) &&
     Boolean(data.rules_proxy_counters) &&
     !data.rules_other_mark_exist;
@@ -50,7 +49,6 @@ export async function runNftCheck() {
     Boolean(data.rules_mangle_exist) ||
     Boolean(data.rules_mangle_counters) ||
     Boolean(data.rules_mangle_output_exist) ||
-    Boolean(data.rules_mangle_output_counters) ||
     Boolean(data.rules_proxy_exist) ||
     Boolean(data.rules_proxy_counters) ||
     !data.rules_other_mark_exist;
@@ -84,11 +82,6 @@ export async function runNftCheck() {
         key: _('Rules mangle output exist'),
         value: '',
       },
-      {
-        state: data.rules_mangle_output_counters ? 'success' : 'error',
-        key: _('Rules mangle output counters'),
-        value: '',
-      },
       {
         state: data.rules_proxy_exist ? 'success' : 'error',
         key: _('Rules proxy exist'),

fe-app-netshift/src/netshift/tabs/diagnostic/diagnostic.store.ts

@@ -46,9 +46,6 @@ export const initialDiagnosticStore: Pick<
     showSingBoxConfig: {
       loading: false,
     },
-    singBoxInstall: {
-      loading: false,
-    },
   },
   diagnosticsRunAction: { loading: false },
   diagnosticsChecks: [

fe-app-netshift/src/netshift/tabs/diagnostic/initController.ts

@@ -316,45 +316,6 @@ async function handleShowSingBoxConfig() {
   }
 }
 
-async function handleInstallSingBox() {
-  const diagnosticsActions = store.get().diagnosticsActions;
-  store.set({
-    diagnosticsActions: {
-      ...diagnosticsActions,
-      singBoxInstall: { loading: true },
-    },
-  });
-
-  const isExtended = store.get().diagnosticsSystemInfo.sing_box_extended === 1;
-
-  try {
-    const result = await NetShiftShellMethods.singBoxComponentAction(
-      isExtended ? 'install_stable' : 'install_extended',
-    );
-
-    if (result.success) {
-      showToast(
-        _('Sing-box core changed, version: ') + (result.version || ''),
-        'success',
-      );
-    } else {
-      logger.error('[DIAGNOSTIC]', 'handleInstallSingBox - e', result);
-      showToast(result.message || _('Failed to execute!'), 'error');
-    }
-  } catch (e) {
-    logger.error('[DIAGNOSTIC]', 'handleInstallSingBox - e', e);
-    showToast(_('Failed to execute!'), 'error');
-  } finally {
-    store.set({
-      diagnosticsActions: {
-        ...diagnosticsActions,
-        singBoxInstall: { loading: false },
-      },
-    });
-    await fetchSystemInfo();
-  }
-}
-
 function renderWikiDisclaimerWidget() {
   const diagnosticsChecks = store.get().diagnosticsChecks;
 
@@ -443,15 +404,6 @@ function renderDiagnosticAvailableActionsWidget() {
       onClick: handleShowSingBoxConfig,
       disabled: atLeastOneServiceCommandLoading,
     },
-    singBoxInstall: {
-      loading: diagnosticsActions.singBoxInstall.loading,
-      visible: true,
-      onClick: handleInstallSingBox,
-      disabled:
-        atLeastOneServiceCommandLoading ||
-        diagnosticsActions.singBoxInstall.loading,
-    },
-    singBoxExtended: store.get().diagnosticsSystemInfo.sing_box_extended,
   });
 
   return preserveScrollForPage(() => {

fe-app-netshift/src/netshift/tabs/diagnostic/partials/renderAvailableActions.ts

@@ -27,8 +27,6 @@ interface IRenderAvailableActionsProps {
   globalCheck: ActionProps;
   viewLogs: ActionProps;
   showSingBoxConfig: ActionProps;
-  singBoxInstall: ActionProps;
-  singBoxExtended: 0 | 1;
 }
 
 export function renderAvailableActions({
@@ -40,8 +38,6 @@ export function renderAvailableActions({
   globalCheck,
   viewLogs,
   showSingBoxConfig,
-  singBoxInstall,
-  singBoxExtended,
 }: IRenderAvailableActionsProps) {
   return E('div', { class: 'pdk_diagnostic-page__right-bar__actions' }, [
     E('b', {}, _('Available actions')),
@@ -122,14 +118,5 @@ export function renderAvailableActions({
         disabled: showSingBoxConfig.disabled,
       }),
     ]),
-    ...insertIf(singBoxInstall.visible, [
-      renderButton({
-        onClick: singBoxInstall.onClick,
-        icon: renderRotateCcwIcon24,
-        text: singBoxExtended ? _('Install stable') : _('Install extended'),
-        loading: singBoxInstall.loading,
-        disabled: singBoxInstall.disabled,
-      }),
-    ]),
   ]);
 }

fe-app-netshift/src/netshift/tabs/index.ts

@@ -1,2 +1,3 @@
 export * from './dashboard';
 export * from './diagnostic';
+export * from './manager';

fe-app-netshift/src/netshift/tabs/manager/cards.ts

@@ -0,0 +1,262 @@
+import { NetShift } from '../../types';
+import { normalizeCompiledVersion } from '../../../helpers/normalizeCompiledVersion';
+
+export type ManagerComponentKey =
+  | 'netshift'
+  | 'sing_box_stock'
+  | 'sing_box_extended';
+
+// `check` = a sing-box update check (routed to the sing-box check method);
+// `check_netshift` = the NetShift card's on-demand check, which is a
+// systemInfo REFRESH (the backend has NO netshift:check_update action — the
+// NetShift latest version comes only from get_system_info.netshift_latest_version).
+// Keeping it a DISTINCT kind guarantees a NetShift check can never be routed to
+// the sing-box check method.
+export type ManagerActionKind =
+  | 'check'
+  | 'check_netshift'
+  | 'update'
+  | 'switch'
+  | 'self_update';
+
+export interface ManagerActionDescriptor {
+  // The store-slice key driving this button's loading flag.
+  loadingKey:
+    | 'netshiftCheck'
+    | 'netshiftUpdate'
+    | 'singBoxStockCheck'
+    | 'singBoxStockAction'
+    | 'singBoxExtendedCheck'
+    | 'singBoxExtendedAction';
+  kind: ManagerActionKind;
+  text: string;
+  // For `update`/`switch`: the backend install action; for `self_update`:
+  // 'self_update'; for `check`: the sing-box check action. The NetShift
+  // `check_netshift` kind has NO backend action (it just refreshes systemInfo).
+  backendAction?:
+    | 'check_update'
+    | 'check_update_stable'
+    | 'install_stable'
+    | 'install_extended'
+    | 'self_update';
+}
+
+export interface ManagerCardTag {
+  label: string;
+  kind: 'neutral' | 'success' | 'warning';
+}
+
+export interface ManagerCardDescriptor {
+  key: ManagerComponentKey;
+  title: string;
+  version: string;
+  installed: boolean;
+  tag?: ManagerCardTag;
+  actions: ManagerActionDescriptor[];
+}
+
+export type ManagerSystemInfo = {
+  netshift_version: string;
+  netshift_latest_version: string;
+  sing_box_version: string;
+  sing_box_extended: 0 | 1;
+};
+
+export type ManagerCheckState = {
+  status: NetShift.ComponentUpdateStatus | null;
+  latest_version: string;
+};
+
+const NOT_INSTALLED = 'not installed';
+
+export function isSingBoxInstalled(systemInfo: ManagerSystemInfo): boolean {
+  const version = systemInfo.sing_box_version;
+
+  return Boolean(version) && version !== NOT_INSTALLED;
+}
+
+/**
+ * Map a check status to a status badge. Pure — same logic as podkop-plus
+ * `getCheckTag`, extended with `not_installed`.
+ */
+export function getCheckTag(
+  status: NetShift.ComponentUpdateStatus | null,
+): ManagerCardTag | undefined {
+  if (!status) {
+    return undefined;
+  }
+
+  if (status === 'latest') {
+    return { label: _('Latest'), kind: 'success' };
+  }
+
+  if (status === 'outdated') {
+    return { label: _('Outdated'), kind: 'warning' };
+  }
+
+  if (status === 'not_installed') {
+    return { label: _('Not installed'), kind: 'neutral' };
+  }
+
+  return { label: _('Dev'), kind: 'neutral' };
+}
+
+// NetShift status is derived PURELY from systemInfo (installed vs latest).
+// There is no NetShift check write into managerChecks — the on-demand check is
+// a systemInfo refresh, after which this re-derives.
+function netshiftStatus(
+  systemInfo: ManagerSystemInfo,
+): NetShift.ComponentUpdateStatus | null {
+  const installed = normalizeCompiledVersion(systemInfo.netshift_version);
+  const latest = systemInfo.netshift_latest_version;
+
+  if (!latest || latest === 'loading' || latest === _('unknown')) {
+    return null;
+  }
+
+  if (installed === 'dev') {
+    return null;
+  }
+
+  return installed === latest ? 'latest' : 'outdated';
+}
+
+function netshiftCard(systemInfo: ManagerSystemInfo): ManagerCardDescriptor {
+  const status = netshiftStatus(systemInfo);
+  const latest = systemInfo.netshift_latest_version;
+  const actions: ManagerActionDescriptor[] = [];
+
+  if (status === 'outdated') {
+    actions.push({
+      loadingKey: 'netshiftUpdate',
+      kind: 'self_update',
+      text:
+        latest && latest !== 'loading'
+          ? _('Install %s').replace('%s', latest)
+          : _('Update NetShift'),
+      backendAction: 'self_update',
+    });
+  } else {
+    actions.push({
+      loadingKey: 'netshiftCheck',
+      kind: 'check_netshift',
+      text: _('Check update'),
+    });
+  }
+
+  return {
+    key: 'netshift',
+    title: 'NetShift',
+    version: normalizeCompiledVersion(systemInfo.netshift_version),
+    installed: true,
+    tag: getCheckTag(status),
+    actions,
+  };
+}
+
+function singBoxStockCard(
+  systemInfo: ManagerSystemInfo,
+  check: ManagerCheckState,
+): ManagerCardDescriptor {
+  const installed = isSingBoxInstalled(systemInfo);
+  const isActive = installed && systemInfo.sing_box_extended === 0;
+  const actions: ManagerActionDescriptor[] = [];
+
+  if (isActive) {
+    if (check.status === 'outdated') {
+      const latest = check.latest_version;
+
+      actions.push({
+        loadingKey: 'singBoxStockAction',
+        kind: 'update',
+        text: latest ? _('Install %s').replace('%s', latest) : _('Update'),
+        backendAction: 'install_stable',
+      });
+    } else {
+      actions.push({
+        loadingKey: 'singBoxStockCheck',
+        kind: 'check',
+        text: _('Check update'),
+        backendAction: 'check_update_stable',
+      });
+    }
+  } else {
+    // Either extended is active, or no sing-box at all → offer switch-to-stable.
+    actions.push({
+      loadingKey: 'singBoxStockAction',
+      kind: 'switch',
+      text: _('Switch to stable'),
+      backendAction: 'install_stable',
+    });
+  }
+
+  return {
+    key: 'sing_box_stock',
+    title: 'sing-box (stock)',
+    version: isActive ? systemInfo.sing_box_version : _('Not installed'),
+    installed: isActive,
+    tag: isActive ? getCheckTag(check.status) : getCheckTag('not_installed'),
+    actions,
+  };
+}
+
+function singBoxExtendedCard(
+  systemInfo: ManagerSystemInfo,
+  check: ManagerCheckState,
+): ManagerCardDescriptor {
+  const installed = isSingBoxInstalled(systemInfo);
+  const isActive = installed && systemInfo.sing_box_extended === 1;
+  const actions: ManagerActionDescriptor[] = [];
+
+  if (isActive) {
+    if (check.status === 'outdated') {
+      const latest = check.latest_version;
+
+      actions.push({
+        loadingKey: 'singBoxExtendedAction',
+        kind: 'update',
+        text: latest ? _('Install %s').replace('%s', latest) : _('Update'),
+        backendAction: 'install_extended',
+      });
+    } else {
+      actions.push({
+        loadingKey: 'singBoxExtendedCheck',
+        kind: 'check',
+        text: _('Check update'),
+        backendAction: 'check_update',
+      });
+    }
+  } else {
+    actions.push({
+      loadingKey: 'singBoxExtendedAction',
+      kind: 'switch',
+      text: _('Switch to extended'),
+      backendAction: 'install_extended',
+    });
+  }
+
+  return {
+    key: 'sing_box_extended',
+    title: 'sing-box (extended)',
+    version: isActive ? systemInfo.sing_box_version : _('Not installed'),
+    installed: isActive,
+    tag: isActive ? getCheckTag(check.status) : getCheckTag('not_installed'),
+    actions,
+  };
+}
+
+/**
+ * Build the three Component Manager cards from systemInfo + per-component check
+ * state. Pure (no DOM, no store) so it is unit-testable; the controller maps
+ * descriptors to DOM + click handlers.
+ */
+export function getComponentCards(
+  systemInfo: ManagerSystemInfo,
+  checks: Record<ManagerComponentKey, ManagerCheckState>,
+): ManagerCardDescriptor[] {
+  return [
+    netshiftCard(systemInfo),
+    singBoxStockCard(systemInfo, checks.sing_box_stock),
+    singBoxExtendedCard(systemInfo, checks.sing_box_extended),
+  ];
+}

fe-app-netshift/src/netshift/tabs/manager/index.ts

@@ -0,0 +1,9 @@
+import { render } from './render';
+import { initController } from './initController';
+import { styles } from './styles';
+
+export const ManagerTab = {
+  render,
+  initController,
+  styles,
+};

fe-app-netshift/src/netshift/tabs/manager/initController.ts

@@ -0,0 +1,434 @@
+import { onMount, preserveScrollForPage } from '../../../helpers';
+import { normalizeCompiledVersion } from '../../../helpers/normalizeCompiledVersion';
+import { showToast } from '../../../helpers/showToast';
+import { renderRotateCcwIcon24, renderSearchIcon24 } from '../../../icons';
+import { renderButton } from '../../../partials';
+import { NetShiftShellMethods } from '../../methods';
+import { logger, store, StoreType } from '../../services';
+import { NetShift } from '../../types';
+import {
+  ManagerActionDescriptor,
+  ManagerCardDescriptor,
+  ManagerComponentKey,
+  getComponentCards,
+} from './cards';
+
+type ManagerActionKey = keyof StoreType['managerActions'];
+
+let managerLifecycleRegistered = false;
+let managerControllerInitialized = false;
+let managerMounted = false;
+
+async function fetchSystemInfo() {
+  const systemInfo = await NetShiftShellMethods.getSystemInfo();
+
+  if (systemInfo.success) {
+    store.set({
+      diagnosticsSystemInfo: {
+        loading: false,
+        ...systemInfo.data,
+        sing_box_extended: systemInfo.data.sing_box_extended === 1 ? 1 : 0,
+      },
+    });
+  } else {
+    store.set({
+      diagnosticsSystemInfo: {
+        loading: false,
+        netshift_version: _('unknown'),
+        netshift_latest_version: _('unknown'),
+        luci_app_version: _('unknown'),
+        sing_box_version: _('unknown'),
+        openwrt_version: _('unknown'),
+        device_model: _('unknown'),
+        sing_box_extended: 0,
+      },
+    });
+  }
+}
+
+function isAnyActionLoading() {
+  return Object.values(store.get().managerActions).some((item) => item.loading);
+}
+
+function isSystemInfoLoading() {
+  return store.get().diagnosticsSystemInfo.loading;
+}
+
+function setActionLoading(action: ManagerActionKey, loading: boolean) {
+  const managerActions = store.get().managerActions;
+
+  store.set({
+    managerActions: {
+      ...managerActions,
+      [action]: { loading },
+    },
+  });
+}
+
+function setCheckResult(
+  component: ManagerComponentKey,
+  status: NetShift.ComponentUpdateStatus | null,
+  latestVersion: string,
+) {
+  const managerChecks = store.get().managerChecks;
+
+  store.set({
+    managerChecks: {
+      ...managerChecks,
+      [component]: {
+        status,
+        latest_version: latestVersion,
+      },
+    },
+  });
+}
+
+function resetCheckResult(component: ManagerComponentKey) {
+  setCheckResult(component, null, '');
+}
+
+function getCheckToastMessage(status: NetShift.ComponentUpdateStatus | null) {
+  if (status === 'outdated') {
+    return _('Update is available');
+  }
+
+  if (status === 'dev') {
+    return _('Installed version is newer than release');
+  }
+
+  if (status === 'not_installed') {
+    return _('Not installed');
+  }
+
+  return _('Latest version is installed');
+}
+
+// Sing-box check: routes to the sing-box check method (stock or extended) and
+// stores the result into the matching managerChecks slice.
+async function runSingBoxCheck(
+  component: ManagerComponentKey,
+  button: ManagerActionDescriptor,
+) {
+  setActionLoading(button.loadingKey, true);
+
+  try {
+    const parsed = await NetShiftShellMethods.singBoxCheckUpdate(
+      button.backendAction === 'check_update_stable'
+        ? 'check_update_stable'
+        : 'check_update',
+    );
+
+    if (!parsed.success) {
+      showToast(parsed.message || _('Failed to execute!'), 'error');
+      return;
+    }
+
+    const status = parsed.status ?? null;
+
+    setCheckResult(component, status, parsed.latest_version || '');
+    showToast(getCheckToastMessage(status), 'success');
+  } catch (error) {
+    logger.error('[MANAGER]', 'runSingBoxCheck failed', error);
+    showToast(_('Failed to execute!'), 'error');
+  } finally {
+    setActionLoading(button.loadingKey, false);
+  }
+}
+
+// NetShift check: the backend has NO netshift:check_update action — NetShift's
+// latest version comes only from get_system_info.netshift_latest_version. So an
+// on-demand NetShift check is a systemInfo REFRESH; the card then re-derives its
+// status from the refreshed installed-vs-latest comparison. We never write a
+// sing-box check result into managerChecks.netshift.
+async function runNetshiftCheck(button: ManagerActionDescriptor) {
+  setActionLoading(button.loadingKey, true);
+
+  try {
+    await fetchSystemInfo();
+    resetCheckResult('netshift');
+
+    const status = store.get().diagnosticsSystemInfo;
+    const installed = normalizeCompiledVersion(status.netshift_version);
+    const latest = status.netshift_latest_version;
+
+    if (!latest || latest === 'loading' || latest === _('unknown')) {
+      showToast(_('Latest version is unknown'), 'success');
+    } else if (installed === 'dev') {
+      showToast(getCheckToastMessage('dev'), 'success');
+    } else {
+      showToast(
+        getCheckToastMessage(installed === latest ? 'latest' : 'outdated'),
+        'success',
+      );
+    }
+  } catch (error) {
+    logger.error('[MANAGER]', 'runNetshiftCheck failed', error);
+    showToast(_('Failed to execute!'), 'error');
+  } finally {
+    setActionLoading(button.loadingKey, false);
+  }
+}
+
+async function runSingBoxMutation(
+  component: ManagerComponentKey,
+  button: ManagerActionDescriptor,
+) {
+  setActionLoading(button.loadingKey, true);
+  showToast(
+    _('Switching sing-box core, this may take a few minutes…'),
+    'success',
+  );
+
+  try {
+    const result = await NetShiftShellMethods.singBoxComponentAction(
+      button.backendAction === 'install_stable'
+        ? 'install_stable'
+        : 'install_extended',
+    );
+
+    if (result.success) {
+      const changed = _('Sing-box core changed, version:');
+
+      showToast(`${changed} ${result.version || ''}`.trim(), 'success');
+      resetCheckResult(component);
+      await fetchSystemInfo();
+    } else {
+      logger.error('[MANAGER]', 'runSingBoxMutation failed', result);
+      showToast(result.message || _('Failed to execute!'), 'error');
+    }
+  } catch (error) {
+    logger.error('[MANAGER]', 'runSingBoxMutation failed', error);
+    showToast(_('Failed to execute!'), 'error');
+  } finally {
+    setActionLoading(button.loadingKey, false);
+  }
+}
+
+function reloadPageAfterSelfUpdate() {
+  window.setTimeout(() => {
+    window.location.reload();
+  }, 1200);
+}
+
+async function runNetshiftSelfUpdate(button: ManagerActionDescriptor) {
+  setActionLoading(button.loadingKey, true);
+  // Warning-style toast: self-update is long and ends in a page reload.
+  showToast(
+    _('Updating NetShift, this may take a few minutes; the page will reload…'),
+    'success',
+    6000,
+  );
+
+  try {
+    const result = await NetShiftShellMethods.netshiftSelfUpdate();
+
+    if (result.success) {
+      const updated = _('NetShift updated, version:');
+
+      showToast(`${updated} ${result.version || ''}`.trim(), 'success', 1200);
+      reloadPageAfterSelfUpdate();
+      return;
+    }
+
+    logger.error('[MANAGER]', 'runNetshiftSelfUpdate failed', result);
+    showToast(result.message || _('Failed to execute!'), 'error');
+    setActionLoading(button.loadingKey, false);
+  } catch (error) {
+    logger.error('[MANAGER]', 'runNetshiftSelfUpdate failed', error);
+    showToast(_('Failed to execute!'), 'error');
+    setActionLoading(button.loadingKey, false);
+  }
+}
+
+function handleManagerAction(
+  card: ManagerCardDescriptor,
+  button: ManagerActionDescriptor,
+) {
+  if (isAnyActionLoading()) {
+    return;
+  }
+
+  if (button.kind === 'check_netshift') {
+    void runNetshiftCheck(button);
+    return;
+  }
+
+  if (button.kind === 'check') {
+    void runSingBoxCheck(card.key, button);
+    return;
+  }
+
+  if (button.kind === 'self_update') {
+    void runNetshiftSelfUpdate(button);
+    return;
+  }
+
+  // `update` / `switch` — both drive the async sing-box install contract.
+  void runSingBoxMutation(card.key, button);
+}
+
+function renderComponentTag(card: ManagerCardDescriptor) {
+  if (!card.tag) {
+    return null;
+  }
+
+  return E(
+    'span',
+    {
+      class: [
+        'pdk_manager-page__component__tag',
+        card.tag.kind === 'success'
+          ? 'pdk_manager-page__component__tag--success'
+          : '',
+        card.tag.kind === 'warning'
+          ? 'pdk_manager-page__component__tag--warning'
+          : '',
+      ]
+        .filter(Boolean)
+        .join(' '),
+    },
+    card.tag.label,
+  );
+}
+
+function renderComponentCard(card: ManagerCardDescriptor) {
+  const managerActions = store.get().managerActions;
+  const anyActionLoading = isAnyActionLoading();
+  const systemInfoLoading = isSystemInfoLoading();
+  const tag = renderComponentTag(card);
+  const headerChildren: Node[] = [
+    E('b', { class: 'pdk_manager-page__component__title' }, card.title),
+  ];
+
+  if (tag) {
+    headerChildren.push(
+      E('div', { class: 'pdk_manager-page__component__status' }, [tag]),
+    );
+  }
+
+  return E('div', { class: 'pdk_manager-page__component' }, [
+    E('div', { class: 'pdk_manager-page__component__header' }, headerChildren),
+    E('div', { class: 'pdk_manager-page__component__version' }, [
+      E(
+        'span',
+        { class: 'pdk_manager-page__component__version__label' },
+        _('Version'),
+      ),
+      E(
+        'span',
+        { class: 'pdk_manager-page__component__version__value' },
+        card.version,
+      ),
+    ]),
+    E(
+      'div',
+      { class: 'pdk_manager-page__component__actions' },
+      card.actions.map((action) => {
+        const loading = managerActions[action.loadingKey].loading;
+
+        return renderButton({
+          text: action.text,
+          icon:
+            action.kind === 'check' || action.kind === 'check_netshift'
+              ? renderSearchIcon24
+              : renderRotateCcwIcon24,
+          loading,
+          disabled: systemInfoLoading || (anyActionLoading && !loading),
+          onClick: () => handleManagerAction(card, action),
+        });
+      }),
+    ),
+  ]);
+}
+
+function renderManagerComponents() {
+  const container = document.getElementById('pdk_manager-components');
+
+  if (!container) {
+    return;
+  }
+
+  const { diagnosticsSystemInfo, managerChecks } = store.get();
+  const renderedComponents = getComponentCards(
+    {
+      netshift_version: normalizeCompiledVersion(
+        diagnosticsSystemInfo.netshift_version,
+      ),
+      netshift_latest_version: diagnosticsSystemInfo.netshift_latest_version,
+      sing_box_version: diagnosticsSystemInfo.sing_box_version,
+      sing_box_extended: diagnosticsSystemInfo.sing_box_extended,
+    },
+    managerChecks,
+  ).map(renderComponentCard);
+
+  return preserveScrollForPage(() => {
+    container.replaceChildren(...renderedComponents);
+  });
+}
+
+function onStoreUpdate(
+  _next: StoreType,
+  _prev: StoreType,
+  diff: Partial<StoreType>,
+) {
+  if (diff.diagnosticsSystemInfo || diff.managerActions || diff.managerChecks) {
+    renderManagerComponents();
+  }
+}
+
+function onPageMount() {
+  onPageUnmount();
+
+  managerMounted = true;
+  store.subscribe(onStoreUpdate);
+  renderManagerComponents();
+  void fetchSystemInfo();
+}
+
+function onPageUnmount() {
+  managerMounted = false;
+  store.unsubscribe(onStoreUpdate);
+  store.reset(['managerActions', 'managerChecks']);
+}
+
+function registerLifecycleListeners() {
+  if (managerLifecycleRegistered) {
+    return;
+  }
+
+  managerLifecycleRegistered = true;
+
+  store.subscribe((next, prev, diff) => {
+    if (
+      diff.tabService &&
+      next.tabService.current !== prev.tabService.current
+    ) {
+      const isManagerVisible = next.tabService.current === 'manager';
+
+      if (isManagerVisible) {
+        return onPageMount();
+      }
+
+      if (managerMounted) {
+        return onPageUnmount();
+      }
+    }
+  });
+}
+
+export async function initController(): Promise<void> {
+  if (managerControllerInitialized) {
+    return;
+  }
+
+  managerControllerInitialized = true;
+
+  onMount('manager-status').then(() => {
+    logger.debug('[MANAGER]', 'initController', 'onMount');
+    registerLifecycleListeners();
+
+    if (store.get().tabService.current === 'manager') {
+      onPageMount();
+    }
+  });
+}

fe-app-netshift/src/netshift/tabs/manager/manager.store.ts

@@ -0,0 +1,20 @@
+import { StoreType } from '../../services';
+
+export const initialManagerStore: Pick<
+  StoreType,
+  'managerActions' | 'managerChecks'
+> = {
+  managerActions: {
+    netshiftCheck: { loading: false },
+    netshiftUpdate: { loading: false },
+    singBoxStockCheck: { loading: false },
+    singBoxStockAction: { loading: false },
+    singBoxExtendedCheck: { loading: false },
+    singBoxExtendedAction: { loading: false },
+  },
+  managerChecks: {
+    netshift: { status: null, latest_version: '' },
+    sing_box_stock: { status: null, latest_version: '' },
+    sing_box_extended: { status: null, latest_version: '' },
+  },
+};

fe-app-netshift/src/netshift/tabs/manager/render.ts

@@ -0,0 +1,8 @@
+export function render() {
+  return E('div', { id: 'manager-status', class: 'pdk_manager-page' }, [
+    E('div', {
+      id: 'pdk_manager-components',
+      class: 'pdk_manager-page__components',
+    }),
+  ]);
+}

fe-app-netshift/src/netshift/tabs/manager/styles.ts

@@ -0,0 +1,109 @@
+// language=CSS
+export const styles = `
+#cbi-netshift-manager-_mount_node > div {
+    width: 100%;
+}
+
+#cbi-netshift-manager > h3 {
+    display: none;
+}
+
+.pdk_manager-page {
+    width: 100%;
+}
+
+.pdk_manager-page__components {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(240px, 1fr));
+    grid-gap: 10px;
+}
+
+@media (max-width: 760px) {
+    .pdk_manager-page__components {
+        grid-template-columns: 1fr;
+    }
+}
+
+.pdk_manager-page__component {
+    border: 2px var(--background-color-low, lightgray) solid;
+    border-radius: 4px;
+    padding: 10px;
+    min-width: 0;
+    display: grid;
+    grid-template-columns: 1fr;
+    grid-row-gap: 10px;
+}
+
+.pdk_manager-page__component__header {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, auto);
+    align-items: start;
+    gap: 8px;
+    min-width: 0;
+}
+
+.pdk_manager-page__component__title {
+    color: var(--text-color-high);
+    line-height: 1.25;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.pdk_manager-page__component__status {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 6px;
+    min-width: 0;
+    max-width: 180px;
+    overflow: hidden;
+}
+
+.pdk_manager-page__component__version {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    grid-column-gap: 6px;
+    align-items: baseline;
+    min-width: 0;
+}
+
+.pdk_manager-page__component__version__label {
+    color: var(--text-color-medium);
+}
+
+.pdk_manager-page__component__version__value {
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+
+.pdk_manager-page__component__tag {
+    flex: 0 0 auto;
+    padding: 2px 5px;
+    border: 1px var(--background-color-high, gray) solid;
+    border-radius: 4px;
+    color: var(--text-color-medium, gray);
+    line-height: 1.2;
+}
+
+.pdk_manager-page__component__tag--success {
+    border-color: var(--success-color-medium, green);
+    color: var(--success-color-medium, green);
+}
+
+.pdk_manager-page__component__tag--warning {
+    border-color: var(--warn-color-medium, orange);
+    color: var(--warn-color-medium, orange);
+}
+
+.pdk_manager-page__component__actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+}
+
+.pdk_manager-page__component__actions > .pdk-partial-button {
+    margin-left: 0;
+}
+`;

fe-app-netshift/src/netshift/tabs/manager/tests/cards.test.js

@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'vitest';
+import { getCheckTag, getComponentCards, isSingBoxInstalled } from '../cards';
+
+const emptyChecks = {
+  netshift: { status: null, latest_version: '' },
+  sing_box_stock: { status: null, latest_version: '' },
+  sing_box_extended: { status: null, latest_version: '' },
+};
+
+function makeSystemInfo(patch = {}) {
+  return {
+    netshift_version: '1.0.0',
+    netshift_latest_version: '1.0.0',
+    sing_box_version: '1.12.0',
+    sing_box_extended: 0,
+    ...patch,
+  };
+}
+
+describe('getCheckTag', () => {
+  it.each([
+    ['latest', { label: 'Latest', kind: 'success' }],
+    ['outdated', { label: 'Outdated', kind: 'warning' }],
+    ['dev', { label: 'Dev', kind: 'neutral' }],
+    ['not_installed', { label: 'Not installed', kind: 'neutral' }],
+  ])('maps status %s to the right badge', (status, expected) => {
+    expect(getCheckTag(status)).toEqual(expected);
+  });
+
+  it('returns undefined for a null status', () => {
+    expect(getCheckTag(null)).toBeUndefined();
+  });
+});
+
+describe('isSingBoxInstalled', () => {
+  it.each([
+    ['1.12.0', true],
+    ['not installed', false],
+    ['', false],
+  ])('treats %s as installed=%s', (version, expected) => {
+    expect(
+      isSingBoxInstalled(makeSystemInfo({ sing_box_version: version })),
+    ).toBe(expected);
+  });
+});
+
+describe('getComponentCards', () => {
+  it('always builds exactly three cards in order', () => {
+    const cards = getComponentCards(makeSystemInfo(), emptyChecks);
+
+    expect(cards.map((c) => c.key)).toEqual([
+      'netshift',
+      'sing_box_stock',
+      'sing_box_extended',
+    ]);
+  });
+
+  it('shows the stock card as installed/active when sing_box_extended=0', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({ sing_box_extended: 0, sing_box_version: '1.12.0' }),
+      emptyChecks,
+    );
+    const [, stock, extended] = cards;
+
+    expect(stock.installed).toBe(true);
+    expect(stock.version).toBe('1.12.0');
+    // No check yet → no badge for the active card.
+    expect(stock.tag).toBeUndefined();
+    expect(stock.actions[0].kind).toBe('check');
+    expect(stock.actions[0].backendAction).toBe('check_update_stable');
+
+    // Inactive extended card → "Not installed" + switch-to-extended.
+    expect(extended.installed).toBe(false);
+    expect(extended.version).toBe('Not installed');
+    expect(extended.actions[0].kind).toBe('switch');
+    expect(extended.actions[0].backendAction).toBe('install_extended');
+  });
+
+  it('mirrors the layout when sing_box_extended=1', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({ sing_box_extended: 1, sing_box_version: '1.12.5' }),
+      emptyChecks,
+    );
+    const [, stock, extended] = cards;
+
+    expect(extended.installed).toBe(true);
+    expect(extended.actions[0].backendAction).toBe('check_update');
+
+    expect(stock.installed).toBe(false);
+    expect(stock.actions[0].kind).toBe('switch');
+    expect(stock.actions[0].backendAction).toBe('install_stable');
+  });
+
+  it('offers switch-to on both cores when sing-box is absent', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({ sing_box_version: 'not installed' }),
+      emptyChecks,
+    );
+    const [, stock, extended] = cards;
+
+    expect(stock.installed).toBe(false);
+    expect(stock.actions[0].kind).toBe('switch');
+    expect(extended.installed).toBe(false);
+    expect(extended.actions[0].kind).toBe('switch');
+  });
+
+  it('turns an outdated stock check into an Install %s update action', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({ sing_box_extended: 0, sing_box_version: '1.12.0' }),
+      {
+        ...emptyChecks,
+        sing_box_stock: { status: 'outdated', latest_version: '1.12.9' },
+      },
+    );
+    const stock = cards[1];
+
+    expect(stock.tag).toEqual({ label: 'Outdated', kind: 'warning' });
+    expect(stock.actions[0].kind).toBe('update');
+    expect(stock.actions[0].backendAction).toBe('install_stable');
+    expect(stock.actions[0].text).toBe('Install 1.12.9');
+  });
+
+  it('derives an outdated NetShift card from systemInfo latest mismatch', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({
+        netshift_version: '1.0.0',
+        netshift_latest_version: '1.1.0',
+      }),
+      emptyChecks,
+    );
+    const netshift = cards[0];
+
+    expect(netshift.tag).toEqual({ label: 'Outdated', kind: 'warning' });
+    expect(netshift.actions[0].kind).toBe('self_update');
+    expect(netshift.actions[0].backendAction).toBe('self_update');
+    expect(netshift.actions[0].text).toBe('Install 1.1.0');
+  });
+
+  it('keeps the NetShift card on Check update when versions match', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({
+        netshift_version: '1.1.0',
+        netshift_latest_version: '1.1.0',
+      }),
+      emptyChecks,
+    );
+    const netshift = cards[0];
+
+    expect(netshift.tag).toEqual({ label: 'Latest', kind: 'success' });
+    // The NetShift check is a DISTINCT kind so it can never be routed to the
+    // sing-box check method.
+    expect(netshift.actions[0].kind).toBe('check_netshift');
+  });
+
+  it('NetShift check action carries NO sing-box backendAction', () => {
+    // C1 regression guard: the NetShift "Check update" must never be a sing-box
+    // check (the backend has no netshift:check_update action). Its action has no
+    // backendAction at all — it triggers a systemInfo refresh in the controller.
+    const cards = getComponentCards(
+      makeSystemInfo({
+        netshift_version: '1.0.0',
+        netshift_latest_version: '1.0.0',
+      }),
+      emptyChecks,
+    );
+    const netshift = cards[0];
+
+    expect(netshift.actions[0].kind).toBe('check_netshift');
+    expect(netshift.actions[0].backendAction).toBeUndefined();
+    expect(['check_update', 'check_update_stable']).not.toContain(
+      netshift.actions[0].backendAction,
+    );
+  });
+
+  it('derives NetShift status purely from systemInfo, ignoring managerChecks', () => {
+    // Even if a (bogus) sing-box-style status leaked into managerChecks.netshift,
+    // the NetShift card must derive its status from systemInfo versions only.
+    const cards = getComponentCards(
+      makeSystemInfo({
+        netshift_version: '1.0.0',
+        netshift_latest_version: '1.0.0',
+      }),
+      {
+        ...emptyChecks,
+        netshift: { status: 'outdated', latest_version: '9.9.9' },
+      },
+    );
+    const netshift = cards[0];
+
+    expect(netshift.tag).toEqual({ label: 'Latest', kind: 'success' });
+    expect(netshift.actions[0].kind).toBe('check_netshift');
+  });
+
+  it('treats an unknown NetShift latest as no status (Check update, no badge)', () => {
+    const cards = getComponentCards(
+      makeSystemInfo({
+        netshift_version: '1.0.0',
+        netshift_latest_version: 'unknown',
+      }),
+      emptyChecks,
+    );
+    const netshift = cards[0];
+
+    expect(netshift.tag).toBeUndefined();
+    expect(netshift.actions[0].kind).toBe('check_netshift');
+  });
+});

fe-app-netshift/src/netshift/types.ts

@@ -120,6 +120,8 @@ export namespace NetShift {
     subscription_url: string;
     subscription_update_interval?: string;
     subscription_group_by_countries?: '0' | '1';
+    subscription_filter_include_keywords?: string[];
+    subscription_filter_exclude_keywords?: string[];
   }
 
   export interface ConfigVpnSection {
@@ -173,6 +175,7 @@ export namespace NetShift {
     bootstrap_dns_server: string;
     bootstrap_dns_status: 0 | 1;
     dhcp_config_status: 0 | 1;
+    dns_via_outbound_tag?: string;
   }
 
   export interface NftRulesCheckResult {
@@ -180,7 +183,6 @@ export namespace NetShift {
     rules_mangle_exist: 0 | 1;
     rules_mangle_counters: 0 | 1;
     rules_mangle_output_exist: 0 | 1;
-    rules_mangle_output_counters: 0 | 1;
     rules_proxy_exist: 0 | 1;
     rules_proxy_counters: 0 | 1;
     rules_other_mark_exist: 0 | 1;
@@ -227,4 +229,23 @@ export namespace NetShift {
   }
 
   export type GetClashApiGroupLatency = Record<string, number>;
+
+  // Component Manager (task-018) — consumes the STABLE backend contract from
+  // task-017. Status union returned by the sync update-check actions.
+  export type ComponentUpdateStatus =
+    | 'latest'
+    | 'outdated'
+    | 'dev'
+    | 'not_installed';
+
+  // Shape echoed by the sync update-check actions:
+  //   component_action sing_box check_update        (extended)
+  //   component_action sing_box check_update_stable (stock)
+  export interface ComponentCheckUpdateResult {
+    success: boolean;
+    current_version?: string;
+    latest_version?: string;
+    status?: ComponentUpdateStatus;
+    message?: string;
+  }
 }

fe-app-netshift/src/styles.ts

@@ -1,10 +1,11 @@
 // language=CSS
-import { DashboardTab, DiagnosticTab } from './netshift';
+import { DashboardTab, DiagnosticTab, ManagerTab } from './netshift';
 import { PartialStyles } from './partials';
 
 export const GlobalStyles = `
 ${DashboardTab.styles}
 ${DiagnosticTab.styles}
+${ManagerTab.styles}
 ${PartialStyles}
 
 

fe-app-netshift/src/validators/tests/validateDns.test.js

@@ -12,11 +12,23 @@ export const additionalValidDns = [
   ['DoH IP with port 443', '1.1.1.1:443/dns-query'],
   ['DoH domain', 'cloudflare-dns.com/dns-query'],
   ['DoH domain with port 443', 'cloudflare-dns.com:443/dns-query'],
+  ['IPv6 address', '2001:db8::1'],
+  ['Bracketed IPv6', '[2001:db8::1]'],
+  ['Bracketed IPv6 with port', '[2001:db8::1]:853'],
+  ['IPv6 DoH path', '2001:db8::1/dns-query'],
+  ['Bracketed IPv6 DoH path with port', '[2001:db8::1]:443/dns-query'],
+];
+
+export const additionalInvalidDns = [
+  ['IPv6 invalid hex', '2001:db8::zzzz'],
+  ['IPv6 group too long', '12345::1'],
+  ['IPv6 triple colon only', ':::'],
+  ['IPv6 multiple compressions', '1::2::3'],
 ];
 
 const validDns = [...validIPs, ...validDomains, ...additionalValidDns];
 
-const invalidDns = [...invalidIPs, ...invalidDomains];
+const invalidDns = [...invalidIPs, ...invalidDomains, ...additionalInvalidDns];
 
 describe('validateDns', () => {
   describe.each(validDns)('Valid dns: %s', (_desc, domain) => {

fe-app-netshift/src/validators/tests/validateIp.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { validateIPV4 } from '../validateIp';
+import { validateIP, validateIPV4, validateIPV6 } from '../validateIp';
 
 export const validIPs = [
   ['Private LAN', '192.168.1.1'],
@@ -21,6 +21,29 @@ export const invalidIPs = [
   ['Trailing dot', '1.2.3.'],
 ];
 
+export const validIPv6 = [
+  ['Loopback', '::1'],
+  ['Compressed', '2001:db8::1'],
+  ['Full form', '2001:0db8:85a3:0000:0000:8a2e:0370:7334'],
+  ['Bracketed', '[2001:db8::1]'],
+  ['Unspecified', '::'],
+  ['Compressed middle', '2001:db8:0:0:1::1'],
+  ['IPv4-mapped', '::ffff:192.168.1.1'],
+  ['IPv4-embedded', '2001:db8::192.168.1.1'],
+];
+
+export const invalidIPv6 = [
+  ['Invalid hex', '2001:db8::zzzz'],
+  ['Group too long', '12345::1'],
+  ['Too many groups', '2001:db8:85a3:0:0:8a2e:370:7334:1234'],
+  ['Triple colon only', ':::'],
+  ['Colon run inside', '1:2:::3'],
+  ['Multiple compressions', '1::2::3'],
+  ['Incomplete (7 groups, no ::)', '1:2:3:4:5:6:7'],
+  ['Bad hex group', 'gggg::1'],
+  ['Too many groups (9)', '1:2:3:4:5:6:7:8:9'],
+];
+
 describe('validateIPV4', () => {
   describe.each(validIPs)('Valid IP: %s', (_desc, ip) => {
     it(`returns {valid:true} for "${ip}"`, () => {
@@ -36,3 +59,41 @@ describe('validateIPV4', () => {
     });
   });
 });
+
+describe('validateIPV6', () => {
+  describe.each(validIPv6)('Valid IPv6: %s', (_desc, ip) => {
+    it(`returns {valid:true} for "${ip}"`, () => {
+      const res = validateIPV6(ip);
+      expect(res.valid).toBe(true);
+    });
+  });
+
+  describe.each([...invalidIPv6, ['IPv4 address', '192.168.1.1']])(
+    'Invalid IPv6: %s',
+    (_desc, ip) => {
+      it(`returns {valid:false} for "${ip}"`, () => {
+        const res = validateIPV6(ip);
+        expect(res.valid).toBe(false);
+      });
+    },
+  );
+});
+
+describe('validateIP', () => {
+  describe.each([...validIPs, ...validIPv6])('Valid IP: %s', (_desc, ip) => {
+    it(`returns {valid:true} for "${ip}"`, () => {
+      const res = validateIP(ip);
+      expect(res.valid).toBe(true);
+    });
+  });
+
+  describe.each([...invalidIPs, ...invalidIPv6])(
+    'Invalid IP: %s',
+    (_desc, ip) => {
+      it(`returns {valid:false} for "${ip}"`, () => {
+        const res = validateIP(ip);
+        expect(res.valid).toBe(false);
+      });
+    },
+  );
+});

fe-app-netshift/src/validators/tests/validateSubnet.test.js

@@ -8,6 +8,10 @@ export const validSubnets = [
   ['CIDR /32', '172.16.0.1/32'],
   ['Loopback', '127.0.0.1'],
   ['Broadcast with mask', '255.255.255.255/32'],
+  ['IPv6 loopback', '::1'],
+  ['IPv6 with CIDR /0', '::/0'],
+  ['IPv6 with CIDR /32', '2001:db8::/32'],
+  ['IPv6 with CIDR /128', '2001:db8::1/128'],
 ];
 
 export const invalidSubnets = [
@@ -22,6 +26,12 @@ export const invalidSubnets = [
   ['Invalid CIDR (negative)', '192.168.1.1/-1'],
   ['CIDR not number', '192.168.1.1/abc'],
   ['Forbidden 0.0.0.0', '0.0.0.0'],
+  ['IPv6 invalid hex', '2001:db8::zzzz'],
+  ['IPv6 CIDR too high', '2001:db8::1/129'],
+  ['IPv6 CIDR negative', '2001:db8::1/-1'],
+  ['IPv6 CIDR not number', '2001:db8::1/abc'],
+  ['IPv6 triple colon with CIDR', ':::/64'],
+  ['IPv6 multiple compressions with CIDR', '1::2::3/64'],
 ];
 
 describe('validateSubnet', () => {

fe-app-netshift/src/validators/tests/validateUrl.test.js

@@ -8,6 +8,9 @@ const validUrls = [
   ['With query', 'https://example.com/?q=test'],
   ['With port', 'http://example.com:8080'],
   ['With subdomain', 'https://sub.example.com'],
+  ['IPv4 host with port and path', 'https://91.199.111.52:2096/sub/abc'],
+  ['IPv4 host with path', 'http://10.0.0.1/x'],
+  ['Bracketed IPv6 host with port and path', 'https://[2001:db8::1]:2096/sub'],
 ];
 
 const invalidUrls = [
@@ -17,6 +20,9 @@ const invalidUrls = [
   ['Unsupported protocol (ws)', 'ws://example.com'],
   ['Empty string', ''],
   ['Without tld', 'https://google'],
+  ['Bad IPv4 host', 'https://999.1.1.1/x'],
+  ['Bad protocol with IP host', 'ftp://1.2.3.4'],
+  ['No host', 'https://'],
 ];
 
 describe('validateUrl', () => {

fe-app-netshift/src/validators/tests/validateVmessUrl.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+import { validateVmessUrl } from '../validateVmessUrl';
+
+// Node global (vitest runs in the node environment); aliased so ESLint's
+// no-undef does not flag the bare `Buffer` identifier.
+const NodeBuffer = globalThis.Buffer;
+
+// Build a vmess:// link from a config object the V2RayN way:
+// vmess:// + base64(JSON).
+const b64 = (obj) => NodeBuffer.from(JSON.stringify(obj)).toString('base64');
+const vmess = (obj) => `vmess://${b64(obj)}`;
+
+const baseConfig = {
+  v: '2',
+  ps: 'node',
+  add: '1.2.3.4',
+  port: 443,
+  id: 'b831381d-6324-4d53-ad4f-8cda48b30811',
+  net: 'ws',
+  type: 'none',
+  host: '',
+  path: '/',
+  tls: 'tls',
+  aid: 0,
+};
+
+// A config whose JSON base64 contains a '+' char (ps:'>>>' forces it).
+// Regression parity with the backend S1 fix.
+const plusB64 = b64({ ...baseConfig, ps: '>>>' });
+
+// An unpadded base64 variant of a valid config (strip trailing '=' padding).
+const unpaddedBody = b64(baseConfig).replace(/=+$/, '');
+
+// The user's REAL key: V2RayN base64(JSON) followed by a "#🇳🇱Ne" display-name
+// fragment. The fragment (emoji/Cyrillic/etc.) used to corrupt the base64 and
+// throw "malformed base64"; stripping it before decode must validate it.
+const realUserKey =
+  'vmess://eyJhZGQiOiJyZW5kZXJlci1zdHJlYW0tMS00MTEubWlycmEubm93IiwiYWlkIjoiMCIsImFsbG93SW5zZWN1cmUiOiIwIiwiYWxsb3dfaW5zZWN1cmUiOiIwIiwiaG9zdCI6InJlbmRlcmVyLXN0cmVhbS0xLTQxMS5taXJyYS5ub3ciLCJpZCI6ImRmOWM5MzU1LWIwMmMtNGMxMi05MDlkLTBkYmViNzI1ZDUyYiIsImluc2VjdXJlIjoiMCIsIm5ldCI6IndzIiwicGF0aCI6Ii9hcGkvdjEvZ3B1LXN0cmVhbS9zb2NrZXQiLCJwb3J0IjoiNDQzIiwicHMiOiLwn4ez8J+HsSBUaGUgTmV0aGVybGFuZHMgfCBbKkNJRFJdIiwic2VjdXJpdHkiOiJhdXRvIiwic25pIjoicmVuZGVyZXItc3RyZWFtLTEtNDExLm1pcnJhLm5vdyIsInRscyI6InRscyIsInYiOiIyIiwidHlwZSI6Im5vbmUiLCJzY3kiOiJhdXRvIiwiYWxwbiI6IiIsImZwIjoiIn0=#🇳🇱Ne';
+
+const validUrls = [
+  ['basic add/port/id', vmess({ add: '1.2.3.4', port: 443, id: 'uuid-1' })],
+  ['full config with net:ws tls:tls', vmess(baseConfig)],
+  ['port as numeric string', vmess({ ...baseConfig, port: '8443' })],
+  ['base64 body containing "+"', `vmess://${plusB64}`],
+  ['unpadded base64 body', `vmess://${unpaddedBody}`],
+  ["user's real key with #🇳🇱Ne fragment", realUserKey],
+  ['fragment label after #', `${vmess(baseConfig)}#label`],
+  ['fragment with spaces after #', `${vmess(baseConfig)}#name with spaces`],
+  ['no fragment (no regression)', vmess(baseConfig)],
+];
+
+const invalidUrls = [
+  ['wrong prefix', `vless://${b64(baseConfig)}`],
+  ['contains space', `vmess://${b64(baseConfig)} `],
+  ['non-base64 body', 'vmess://!!!not base64!!!'],
+  [
+    'base64 of non-JSON',
+    `vmess://${NodeBuffer.from('not json at all').toString('base64')}`,
+  ],
+  [
+    'base64 of JSON array',
+    `vmess://${NodeBuffer.from('[1,2,3]').toString('base64')}`,
+  ],
+  ['missing add', vmess({ port: 443, id: 'uuid-1' })],
+  ['empty add', vmess({ add: '', port: 443, id: 'uuid-1' })],
+  ['missing id', vmess({ add: '1.2.3.4', port: 443 })],
+  ['empty id', vmess({ add: '1.2.3.4', port: 443, id: '' })],
+  ['port 0', vmess({ add: '1.2.3.4', port: 0, id: 'uuid-1' })],
+  ['port 99999', vmess({ add: '1.2.3.4', port: 99999, id: 'uuid-1' })],
+  ['non-numeric port', vmess({ add: '1.2.3.4', port: 'abc', id: 'uuid-1' })],
+];
+
+describe('validateVmessUrl', () => {
+  describe.each(validUrls)('Valid URL: %s', (_desc, url) => {
+    it(`returns valid=true for "${url}"`, () => {
+      const res = validateVmessUrl(url);
+      expect(res.valid).toBe(true);
+      expect(res.message).toBe('Valid');
+    });
+  });
+
+  describe.each(invalidUrls)('Invalid URL: %s', (_desc, url) => {
+    it(`returns valid=false for "${url}"`, () => {
+      const res = validateVmessUrl(url);
+      expect(res.valid).toBe(false);
+    });
+  });
+
+  it('reports the wrong-prefix message', () => {
+    const res = validateVmessUrl('http://example.com');
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: must start with vmess://');
+  });
+
+  it('reports malformed base64', () => {
+    const res = validateVmessUrl('vmess://@@@@');
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: malformed base64');
+  });
+
+  it('reports malformed JSON', () => {
+    const res = validateVmessUrl(
+      `vmess://${NodeBuffer.from('definitely not json').toString('base64')}`,
+    );
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: malformed JSON');
+  });
+
+  it('reports missing address', () => {
+    const res = validateVmessUrl(vmess({ port: 443, id: 'uuid-1' }));
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: missing address');
+  });
+
+  it('reports missing id', () => {
+    const res = validateVmessUrl(vmess({ add: '1.2.3.4', port: 443 }));
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: missing id');
+  });
+
+  it('reports invalid port', () => {
+    const res = validateVmessUrl(
+      vmess({ add: '1.2.3.4', port: 99999, id: 'uuid-1' }),
+    );
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: invalid port');
+  });
+
+  it('confirms the "+"-containing base64 fixture really contains "+"', () => {
+    expect(plusB64).toContain('+');
+  });
+
+  it("validates the user's real #🇳🇱Ne-fragment key", () => {
+    const res = validateVmessUrl(realUserKey);
+    expect(res.valid).toBe(true);
+    expect(res.message).toBe('Valid');
+  });
+
+  it('strips a fragment with spaces (whitespace check runs on base64 only)', () => {
+    const res = validateVmessUrl(`${vmess(baseConfig)}#name with spaces`);
+    expect(res.valid).toBe(true);
+    expect(res.message).toBe('Valid');
+  });
+
+  it('still rejects whitespace inside the base64 body (no fragment)', () => {
+    const res = validateVmessUrl(`vmess://${b64(baseConfig)} `);
+    expect(res.valid).toBe(false);
+    expect(res.message).toBe('Invalid VMess URL: must not contain spaces');
+  });
+});

fe-app-netshift/src/validators/validateDns.ts

@@ -1,5 +1,5 @@
 import { validateDomain } from './validateDomain';
-import { validateIPV4 } from './validateIp';
+import { validateIPV4, validateIPV6 } from './validateIp';
 import { ValidationResult } from './types';
 
 export function validateDNS(value: string): ValidationResult {
@@ -7,13 +7,29 @@ export function validateDNS(value: string): ValidationResult {
     return { valid: false, message: _('DNS server address cannot be empty') };
   }
 
-  const cleanedValueWithoutPort = value.replace(/:(\d+)(?=\/|$)/, '');
-  const cleanedIpWithoutPath = cleanedValueWithoutPort.split('/')[0];
+  const valueBeforePath = value.split('/')[0];
+  let cleanedValueWithoutPort = value;
+  let cleanedIpWithoutPath = valueBeforePath;
+
+  if (valueBeforePath.startsWith('[')) {
+    const closingBracketIndex = valueBeforePath.indexOf(']');
+
+    if (closingBracketIndex > 0) {
+      cleanedIpWithoutPath = valueBeforePath.slice(1, closingBracketIndex);
+    }
+  } else if ((valueBeforePath.match(/:/g) || []).length < 2) {
+    cleanedValueWithoutPort = value.replace(/:(\d+)(?=\/|$)/, '');
+    cleanedIpWithoutPath = cleanedValueWithoutPort.split('/')[0];
+  }
 
   if (validateIPV4(cleanedIpWithoutPath).valid) {
     return { valid: true, message: _('Valid') };
   }
 
+  if (validateIPV6(cleanedIpWithoutPath).valid) {
+    return { valid: true, message: _('Valid') };
+  }
+
   if (validateDomain(cleanedValueWithoutPort).valid) {
     return { valid: true, message: _('Valid') };
   }
@@ -21,7 +37,7 @@ export function validateDNS(value: string): ValidationResult {
   return {
     valid: false,
     message: _(
-      'Invalid DNS server format. Examples: 8.8.8.8 or dns.example.com or dns.example.com/nicedns for DoH',
+      'Invalid DNS server format. Examples: 8.8.8.8, [::1], dns.example.com, or dns.example.com/dns-query for DoH',
     ),
   };
 }

fe-app-netshift/src/validators/validateIp.ts

@@ -10,3 +10,102 @@ export function validateIPV4(ip: string): ValidationResult {
 
   return { valid: false, message: _('Invalid IP address') };
 }
+
+const HEXTET_REGEX = /^[0-9a-fA-F]{1,4}$/;
+
+function isHextet(group: string): boolean {
+  return HEXTET_REGEX.test(group);
+}
+
+function isEmbeddedIPv4(group: string): boolean {
+  return validateIPV4(group).valid;
+}
+
+// Validates one side (the part before or after "::") as a list of hextets.
+// The trailing group may be a dotted IPv4 (embedded/IPv4-mapped IPv6), which
+// counts as TWO 16-bit groups. Returns the 16-bit group count, or null on any
+// invalid group.
+function countGroups(side: string, allowEmbeddedIPv4: boolean): number | null {
+  if (side === '') {
+    return 0;
+  }
+
+  const groups = side.split(':');
+
+  for (let i = 0; i < groups.length; i++) {
+    const group = groups[i];
+    const isLast = i === groups.length - 1;
+
+    if (allowEmbeddedIPv4 && isLast && group.includes('.')) {
+      if (!isEmbeddedIPv4(group)) {
+        return null;
+      }
+
+      continue;
+    }
+
+    if (!isHextet(group)) {
+      return null;
+    }
+  }
+
+  // An embedded IPv4 tail occupies two 16-bit groups instead of one.
+  const lastGroup = groups[groups.length - 1];
+  const embeddedExtra =
+    allowEmbeddedIPv4 && lastGroup.includes('.') && isEmbeddedIPv4(lastGroup)
+      ? 1
+      : 0;
+
+  return groups.length + embeddedExtra;
+}
+
+export function validateIPV6(ip: string): ValidationResult {
+  const stripped = ip.replace(/^\[/, '').replace(/\]$/, '');
+  const invalid: ValidationResult = {
+    valid: false,
+    message: _('Invalid IPv6 address'),
+  };
+
+  // At most one "::" compression is allowed.
+  const doubleColonCount = stripped.split('::').length - 1;
+  if (doubleColonCount > 1) {
+    return invalid;
+  }
+
+  if (doubleColonCount === 1) {
+    const [head, tail] = stripped.split('::');
+
+    const headGroups = countGroups(head, true);
+    const tailGroups = countGroups(tail, true);
+
+    if (headGroups === null || tailGroups === null) {
+      return invalid;
+    }
+
+    // "::" must replace at least one group, so the explicit groups can total
+    // at most 7 (it stands in for one or more zero groups).
+    if (headGroups + tailGroups > 7) {
+      return invalid;
+    }
+
+    return { valid: true, message: _('Valid') };
+  }
+
+  // No "::" → must be exactly 8 groups, all explicit.
+  const totalGroups = countGroups(stripped, true);
+  if (totalGroups === 8) {
+    return { valid: true, message: _('Valid') };
+  }
+
+  return invalid;
+}
+
+export function validateIP(ip: string): ValidationResult {
+  const ipv4 = validateIPV4(ip);
+
+  if (ipv4.valid) {
+    return ipv4;
+  }
+
+  return validateIPV6(ip);
+}

fe-app-netshift/src/validators/validateProxyUrl.ts

@@ -4,6 +4,7 @@ import { validateVlessUrl } from './validateVlessUrl';
 import { validateTrojanUrl } from './validateTrojanUrl';
 import { validateSocksUrl } from './validateSocksUrl';
 import { validateHysteria2Url } from './validateHysteriaUrl';
+import { validateVmessUrl } from './validateVmessUrl';
 
 // TODO refactor current validation and add tests
 export function validateProxyUrl(url: string): ValidationResult {
@@ -21,6 +22,10 @@ export function validateProxyUrl(url: string): ValidationResult {
     return validateTrojanUrl(trimmedUrl);
   }
 
+  if (trimmedUrl.startsWith('vmess://')) {
+    return validateVmessUrl(trimmedUrl);
+  }
+
   if (/^socks(4|4a|5):\/\//.test(trimmedUrl)) {
     return validateSocksUrl(trimmedUrl);
   }
@@ -35,7 +40,7 @@ export function validateProxyUrl(url: string): ValidationResult {
   return {
     valid: false,
     message: _(
-      'URL must start with vless://, ss://, trojan://, socks4/5://, or hysteria2://hy2://',
+      'URL must start with vless://, vmess://, ss://, trojan://, socks4/5://, or hysteria2://hy2://',
     ),
   };
 }

fe-app-netshift/src/validators/validateSubnet.ts

@@ -1,39 +1,59 @@
 import { ValidationResult } from './types';
-import { validateIPV4 } from './validateIp';
+import { validateIPV4, validateIPV6 } from './validateIp';
 
 export function validateSubnet(value: string): ValidationResult {
-  // Must be in form X.X.X.X or X.X.X.X/Y
   const subnetRegex = /^(\d{1,3}\.){3}\d{1,3}(?:\/\d{1,2})?$/;
 
-  if (!subnetRegex.test(value)) {
-    return {
-      valid: false,
-      message: _('Invalid format. Use X.X.X.X or X.X.X.X/Y'),
-    };
-  }
+  if (subnetRegex.test(value)) {
+    const [ip, cidr] = value.split('/');
 
-  const [ip, cidr] = value.split('/');
-
-  if (ip === '0.0.0.0') {
-    return { valid: false, message: _('IP address 0.0.0.0 is not allowed') };
-  }
-
-  const ipCheck = validateIPV4(ip);
-  if (!ipCheck.valid) {
-    return ipCheck;
-  }
-
-  // Validate CIDR if present
-  if (cidr) {
-    const cidrNum = parseInt(cidr, 10);
-
-    if (cidrNum < 0 || cidrNum > 32) {
-      return {
-        valid: false,
-        message: _('CIDR must be between 0 and 32'),
-      };
+    if (ip === '0.0.0.0') {
+      return { valid: false, message: _('IP address 0.0.0.0 is not allowed') };
     }
+
+    const ipCheck = validateIPV4(ip);
+    if (!ipCheck.valid) {
+      return ipCheck;
+    }
+
+    if (cidr) {
+      const cidrNum = parseInt(cidr, 10);
+
+      if (cidrNum < 0 || cidrNum > 32) {
+        return {
+          valid: false,
+          message: _('CIDR must be between 0 and 32'),
+        };
+      }
+    }
+
+    return { valid: true, message: _('Valid') };
   }
 
-  return { valid: true, message: _('Valid') };
+  const ipv6CidrRegex = /^([0-9a-fA-F:]+(?:\/[0-9]{1,3})?)$/;
+  if (ipv6CidrRegex.test(value)) {
+    const [ip, cidr] = value.split('/');
+    const ipCheck = validateIPV6(ip);
+
+    if (!ipCheck.valid) {
+      return ipCheck;
+    }
+
+    if (cidr) {
+      const cidrNum = parseInt(cidr, 10);
+      if (cidrNum < 0 || cidrNum > 128) {
+        return {
+          valid: false,
+          message: _('IPv6 CIDR must be between 0 and 128'),
+        };
+      }
+    }
+
+    return { valid: true, message: _('Valid') };
+  }
+
+  return {
+    valid: false,
+    message: _('Invalid format. Use X.X.X.X/Y or IPv6/Y'),
+  };
 }

fe-app-netshift/src/validators/validateUrl.ts

@@ -1,4 +1,45 @@
 import { ValidationResult } from './types';
+import { validateDomain } from './validateDomain';
+import { validateIPV4, validateIPV6 } from './validateIp';
+
+// Extracts the bare host from a URL, stripping the scheme, optional userinfo,
+// the port, and the path/query/fragment. A bracketed IPv6 literal (e.g.
+// "[2001:db8::1]") is unwrapped to "2001:db8::1".
+function extractHost(url: string): string {
+  // Strip scheme://
+  const schemeIndex = url.indexOf('://');
+  let rest = schemeIndex === -1 ? url : url.slice(schemeIndex + 3);
+
+  // Strip path/query/fragment (everything from the first '/', '?' or '#').
+  const pathIndex = rest.search(/[/?#]/);
+  if (pathIndex !== -1) {
+    rest = rest.slice(0, pathIndex);
+  }
+
+  // Strip optional userinfo ("user:pass@").
+  const atIndex = rest.lastIndexOf('@');
+  if (atIndex !== -1) {
+    rest = rest.slice(atIndex + 1);
+  }
+
+  // Bracketed IPv6 literal: "[2001:db8::1]:2096" -> "2001:db8::1".
+  if (rest.startsWith('[')) {
+    const closeIndex = rest.indexOf(']');
+    if (closeIndex !== -1) {
+      return rest.slice(1, closeIndex);
+    }
+    // Unterminated bracket: drop the leading '[' and any ':port' suffix.
+    return rest.slice(1).split(':')[0];
+  }
+
+  // Bare host: strip a trailing ":port".
+  const colonIndex = rest.lastIndexOf(':');
+  if (colonIndex !== -1) {
+    rest = rest.slice(0, colonIndex);
+  }
+
+  return rest;
+}
 
 export function validateUrl(
   url: string,
@@ -19,12 +60,18 @@ export function validateUrl(
         protocols.join(', '),
     };
 
-  const regex = new RegExp(
-    `^(?:${protocols.map((p) => p.replace(':', '')).join('|')})://` +
-      `(?:[A-Za-z0-9-]+\\.)+[A-Za-z]{2,}(?::\\d+)?(?:/[^\\s]*)?$`,
-  );
+  const host = extractHost(url);
 
-  if (regex.test(url)) {
+  if (!host) {
+    return { valid: false, message: _('Invalid URL format') };
+  }
+
+  const isValidHost =
+    validateIPV4(host).valid ||
+    validateIPV6(host).valid ||
+    validateDomain(host).valid;
+
+  if (isValidHost) {
     return { valid: true, message: _('Valid') };
   }
 

fe-app-netshift/src/validators/validateVmessUrl.ts

@@ -0,0 +1,87 @@
+import { ValidationResult } from './types';
+
+export function validateVmessUrl(url: string): ValidationResult {
+  if (!url.startsWith('vmess://')) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: must start with vmess://'),
+    };
+  }
+
+  const body = url.slice('vmess://'.length);
+
+  // The optional `#fragment` is the server display name (like #name in
+  // vless/ss/trojan); the canonical name also lives in the JSON `ps` field.
+  // Strip it BEFORE base64 decode (cut at the first '#'); the base64 body
+  // never contains '#', so this is safe and matches the other schemes.
+  const b64 = body.split('#')[0];
+
+  // Whitespace ordering: validate AFTER stripping the fragment, and only on
+  // the base64 part. The base64 itself must contain no whitespace, but a
+  // display-name fragment (e.g. "#The Netherlands") legitimately may.
+  if (/\s/.test(b64)) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: must not contain spaces'),
+    };
+  }
+
+  // VMess (V2RayN) is vmess:// + base64(JSON), not a user@host URL.
+  // Tolerate unpadded base64 by right-padding to a multiple of 4, matching
+  // the backend fix.
+  const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+
+  let decoded: string;
+  try {
+    decoded = atob(padded);
+  } catch (_e) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: malformed base64'),
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch (_e) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: malformed JSON'),
+    };
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: malformed JSON'),
+    };
+  }
+
+  const config = parsed as Record<string, unknown>;
+
+  if (typeof config.add !== 'string' || config.add.length === 0) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: missing address'),
+    };
+  }
+
+  if (typeof config.id !== 'string' || config.id.length === 0) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: missing id'),
+    };
+  }
+
+  const portNum = Number(config.port);
+
+  if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) {
+    return {
+      valid: false,
+      message: _('Invalid VMess URL: invalid port'),
+    };
+  }
+
+  return { valid: true, message: _('Valid') };
+}

luci-app-netshift/htdocs/luci-static/resources/view/netshift/manager.js

@@ -0,0 +1,22 @@
+"use strict";
+"require baseclass";
+"require form";
+"require ui";
+"require uci";
+"require fs";
+"require view.netshift.main as main";
+
+function createManagerContent(section) {
+  const o = section.option(form.DummyValue, "_mount_node");
+  o.rawhtml = true;
+  o.cfgvalue = () => {
+    main.ManagerTab.initController();
+    return main.ManagerTab.render();
+  };
+}
+
+const EntryPoint = {
+  createManagerContent,
+};
+
+return baseclass.extend(EntryPoint);

luci-app-netshift/htdocs/luci-static/resources/view/netshift/netshift.js

@@ -17,6 +17,9 @@
 // Diagnostic content
 "require view.netshift.diagnostic as diagnostic";
 
+// Component Manager content
+"require view.netshift.manager as manager";
+
 const EntryPoint = {
   async render() {
     main.injectGlobalStyles();
@@ -73,6 +76,21 @@ const EntryPoint = {
     // Render diagnostic content
     diagnostic.createDiagnosticContent(diagnosticSection);
 
+    // Component Manager tab
+    const managerSection = netshiftMap.section(
+      form.TypedSection,
+      "manager",
+      _("Component Manager"),
+    );
+    managerSection.anonymous = true;
+    managerSection.addremove = false;
+    managerSection.cfgsections = function () {
+      return ["manager"];
+    };
+
+    // Render Component Manager content
+    manager.createManagerContent(managerSection);
+
     // Dashboard tab
     const dashboardSection = netshiftMap.section(
       form.TypedSection,

luci-app-netshift/htdocs/luci-static/resources/view/netshift/section.js

@@ -35,7 +35,9 @@ function createSectionContent(section) {
     form.TextValue,
     "proxy_string",
     _("Proxy Configuration URL"),
-    _("vless://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links")
+    _(
+      "vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links",
+    ),
   );
   o.depends({ connection_type: "proxy", proxy_config_type: "url" });
   o.rows = 5;
@@ -87,7 +89,9 @@ function createSectionContent(section) {
     form.Value,
     "subscription_url",
     _("Subscription URL"),
-    _("Enter the subscription URL to fetch proxy configurations from your provider"),
+    _(
+      "Enter the subscription URL to fetch proxy configurations from your provider",
+    ),
   );
   o.depends({ connection_type: "proxy", proxy_config_type: "subscription" });
   o.placeholder = "https://example.com/api/sub";
@@ -106,6 +110,20 @@ function createSectionContent(section) {
     return validation.message;
   };
 
+  o = section.option(
+    form.Flag,
+    "subscription_insecure",
+    _("Allow insecure TLS for subscription fetch"),
+    _("Disables TLS certificate verification when downloading the subscription.") +
+      " " +
+      _("Use only for IP-host panels that serve an invalid or self-signed certificate.") +
+      " " +
+      _("This is a security trade-off: an attacker could intercept the fetch."),
+  );
+  o.default = "0";
+  o.rmempty = false;
+  o.depends({ connection_type: "proxy", proxy_config_type: "subscription" });
+
   o = section.option(
     form.ListValue,
     "subscription_update_interval",
@@ -125,17 +143,43 @@ function createSectionContent(section) {
     form.Flag,
     "subscription_group_by_countries",
     _("Группировать по странам"),
-    _("Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"),
+    _(
+      "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы",
+    ),
   );
   o.default = "0";
   o.rmempty = false;
   o.depends({ connection_type: "proxy", proxy_config_type: "subscription" });
 
+  o = section.option(
+    form.DynamicList,
+    "subscription_filter_include_keywords",
+    _("Include servers by keyword"),
+    _(
+      "Keep only subscription servers whose name contains at least one of these keywords (case-insensitive). Leave empty to keep all.",
+    ),
+  );
+  o.depends({ connection_type: "proxy", proxy_config_type: "subscription" });
+  o.rmempty = true;
+
+  o = section.option(
+    form.DynamicList,
+    "subscription_filter_exclude_keywords",
+    _("Exclude servers by keyword"),
+    _(
+      "Drop subscription servers whose name contains any of these keywords (case-insensitive).",
+    ),
+  );
+  o.depends({ connection_type: "proxy", proxy_config_type: "subscription" });
+  o.rmempty = true;
+
   o = section.option(
     form.DynamicList,
     "selector_proxy_links",
     _("Selector Proxy Links"),
-    _("vless://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links")
+    _(
+      "vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links",
+    ),
   );
   o.depends({ connection_type: "proxy", proxy_config_type: "selector" });
   o.rmempty = false;
@@ -158,7 +202,9 @@ function createSectionContent(section) {
     form.DynamicList,
     "urltest_proxy_links",
     _("URLTest Proxy Links"),
-    _("vless://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links")
+    _(
+      "vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links",
+    ),
   );
   o.depends({ connection_type: "proxy", proxy_config_type: "urltest" });
   o.rmempty = false;
@@ -181,7 +227,7 @@ function createSectionContent(section) {
     form.ListValue,
     "urltest_check_interval",
     _("URLTest Check Interval"),
-    _("The interval between connectivity tests")
+    _("The interval between connectivity tests"),
   );
   o.value("30s", _("Every 30 seconds"));
   o.value("1m", _("Every 1 minute"));
@@ -195,7 +241,9 @@ function createSectionContent(section) {
     form.Value,
     "urltest_tolerance",
     _("URLTest Tolerance"),
-    _("The maximum difference in response times (ms) allowed when comparing servers")
+    _(
+      "The maximum difference in response times (ms) allowed when comparing servers",
+    ),
   );
   o.default = "50";
   o.rmempty = false;
@@ -208,23 +256,38 @@ function createSectionContent(section) {
 
     const parsed = parseFloat(value);
 
-    if (/^[0-9]+$/.test(value) && !isNaN(parsed) && isFinite(parsed) && parsed >= 50 && parsed <= 1000) {
+    if (
+      /^[0-9]+$/.test(value) &&
+      !isNaN(parsed) &&
+      isFinite(parsed) &&
+      parsed >= 50 &&
+      parsed <= 1000
+    ) {
       return true;
     }
 
-    return _('Must be a number in the range of 50 - 1000');
+    return _("Must be a number in the range of 50 - 1000");
   };
 
   o = section.option(
     form.Value,
     "urltest_testing_url",
     _("URLTest Testing URL"),
-    _("The URL used to test server connectivity")
+    _("The URL used to test server connectivity"),
+  );
+  o.value(
+    "https://www.gstatic.com/generate_204",
+    "https://www.gstatic.com/generate_204 (Google)",
+  );
+  o.value(
+    "https://cp.cloudflare.com/generate_204",
+    "https://cp.cloudflare.com/generate_204 (Cloudflare)",
   );
-  o.value("https://www.gstatic.com/generate_204", "https://www.gstatic.com/generate_204 (Google)");
-  o.value("https://cp.cloudflare.com/generate_204", "https://cp.cloudflare.com/generate_204 (Cloudflare)");
   o.value("https://captive.apple.com", "https://captive.apple.com (Apple)");
-  o.value("https://connectivity-check.ubuntu.com", "https://connectivity-check.ubuntu.com (Ubuntu)")
+  o.value(
+    "https://connectivity-check.ubuntu.com",
+    "https://connectivity-check.ubuntu.com (Ubuntu)",
+  );
   o.default = "https://www.gstatic.com/generate_204";
   o.rmempty = false;
   o.depends({ connection_type: "proxy", proxy_config_type: "urltest" });
@@ -254,6 +317,23 @@ function createSectionContent(section) {
   o.depends("connection_type", "proxy");
   o.rmempty = false;
 
+  o = section.option(
+    form.Flag,
+    "global_proxy",
+    _("Global Proxy"),
+    _("Route all unmatched traffic through this section's outbound.") +
+      " " +
+      _(
+        "When enabled, traffic not matching any other section's lists will go through this proxy.",
+      ) +
+      " " +
+      _("Use with Exclusion sections to route specific domains directly.") +
+      " " +
+      _("Only one section can be global at a time."),
+  );
+  o.default = "0";
+  o.rmempty = false;
+
   o = section.option(
     widgets.DeviceSelect,
     "interface",
@@ -350,7 +430,7 @@ function createSectionContent(section) {
     "community_lists",
     _("Community Lists"),
     _("Select a predefined list for routing") +
-    ' <a href="https://github.com/itdoginfo/allow-domains" target="_blank">github.com/itdoginfo/allow-domains</a>',
+      ' <a href="https://github.com/itdoginfo/allow-domains" target="_blank">github.com/itdoginfo/allow-domains</a>',
   );
   o.placeholder = "Service list";
   Object.entries(main.DOMAIN_LIST_OPTIONS).forEach(([key, label]) => {
@@ -557,7 +637,7 @@ function createSectionContent(section) {
     _("User Subnets List"),
     _(
       "Enter subnets in CIDR notation or single IP addresses, separated by commas, spaces, or newlines. " +
-      "You can add comments using //",
+        "You can add comments using //",
     ),
   );
   o.placeholder =
@@ -730,7 +810,7 @@ function createSectionContent(section) {
     _("Mixed Proxy Port"),
     _(
       "Specify the port number on which the mixed proxy will run for this section. " +
-      "Make sure the selected port is not used by another service",
+        "Make sure the selected port is not used by another service",
     ),
   );
   o.default = "2080";

luci-app-netshift/htdocs/luci-static/resources/view/netshift/settings.js

@@ -62,6 +62,51 @@ function createSettingsContent(section) {
     return validation.message;
   };
 
+  o = section.option(
+    form.Flag,
+    "dns_via_outbound",
+    _("Route main DNS through proxy/VPN"),
+    _(
+      "Send upstream DNS queries through a proxy/VPN outbound instead of directly. Bootstrap DNS always stays direct.",
+    ),
+  );
+  o.default = "0";
+  o.rmempty = false;
+
+  o = section.option(
+    form.ListValue,
+    "dns_outbound_section",
+    _("DNS outbound section"),
+    _(
+      "Which proxy/VPN section carries the DNS. Leave unset to use the first configured outbound.",
+    ),
+  );
+  o.rmempty = true;
+  o.depends("dns_via_outbound", "1");
+  o.cfgvalue = function (section_id) {
+    return uci.get("netshift", section_id, "dns_outbound_section");
+  };
+  o.load = function () {
+    const sections = this.map?.data?.state?.values?.netshift ?? {};
+
+    this.keylist = [];
+    this.vallist = [];
+
+    for (const secName in sections) {
+      const sec = sections[secName];
+      if (
+        sec[".type"] === "section" &&
+        sec["connection_type"] !== "block" &&
+        sec["connection_type"] !== "exclusion"
+      ) {
+        this.keylist.push(secName);
+        this.vallist.push(secName);
+      }
+    }
+
+    return Promise.resolve();
+  };
+
   o = section.option(
     form.Value,
     "dns_rewrite_ttl",
@@ -148,9 +193,7 @@ function createSettingsContent(section) {
     }
 
     // Reject lan*
-    if (
-        value.startsWith("lan")
-    ) {
+    if (value.startsWith("lan")) {
       return false;
     }
 
@@ -244,7 +287,9 @@ function createSettingsContent(section) {
     form.Flag,
     "enable_yacd_wan_access",
     _("Enable YACD WAN Access"),
-    _("Allows access to YACD from the WAN. Make sure to open the appropriate port in your firewall."),
+    _(
+      "Allows access to YACD from the WAN. Make sure to open the appropriate port in your firewall.",
+    ),
   );
   o.depends("enable_yacd", "1");
   o.default = "0";
@@ -254,7 +299,9 @@ function createSettingsContent(section) {
     form.Value,
     "yacd_secret_key",
     _("YACD Secret Key"),
-    _("Secret key for authenticating remote access to YACD when WAN access is enabled."),
+    _(
+      "Secret key for authenticating remote access to YACD when WAN access is enabled.",
+    ),
   );
   o.depends("enable_yacd_wan_access", "1");
   o.rmempty = false;
@@ -311,7 +358,11 @@ function createSettingsContent(section) {
 
     for (const secName in sections) {
       const sec = sections[secName];
-      if (sec[".type"] === "section" && sec['connection_type'] !== 'block' && sec['connection_type'] !== 'exclusion') {
+      if (
+        sec[".type"] === "section" &&
+        sec["connection_type"] !== "block" &&
+        sec["connection_type"] !== "exclusion"
+      ) {
         this.keylist.push(secName);
         this.vallist.push(secName);
       }
@@ -382,9 +433,7 @@ function createSettingsContent(section) {
     form.ListValue,
     "log_level",
     _("Log Level"),
-    _(
-      "Select the log level for sing-box",
-    ),
+    _("Select the log level for sing-box"),
   );
   o.value("trace", "Trace");
   o.value("debug", "Debug");
@@ -407,6 +456,38 @@ function createSettingsContent(section) {
   o.default = "0";
   o.rmempty = false;
 
+  o = section.option(
+    form.Flag,
+    "block_doh",
+    _("Block DoH Servers"),
+    _("Block direct connections to known public DNS-over-HTTPS (DoH) servers.") +
+      " " +
+      _(
+        "This prevents applications from bypassing the router's DNS filtering by using their own encrypted DNS.",
+      ) +
+      " " +
+      _(
+        "Affects Cloudflare, Google, Quad9, OpenDNS, AdGuard, and Yandex public DoH servers.",
+      ) +
+      " " +
+      _(
+        "Note: if your upstream DNS type is set to 'DoH', enable this only after switching to UDP or DoT.",
+      ),
+  );
+  o.default = "0";
+  o.rmempty = false;
+
+  o = section.option(
+    form.Flag,
+    "enable_ipv6",
+    _("Enable IPv6 Support"),
+    _("Enable IPv6 TProxy routing, IPv6 DNS inbound, and IPv6 FakeIP support.") +
+      " " +
+      _("Use this only when the router has working IPv6 connectivity."),
+  );
+  o.default = "0";
+  o.rmempty = false;
+
   o = section.option(
     form.DynamicList,
     "routing_excluded_ips",
@@ -421,7 +502,7 @@ function createSettingsContent(section) {
       return true;
     }
 
-    const validation = main.validateIPV4(value);
+    const validation = main.validateIP(value);
 
     if (validation.valid) {
       return true;

luci-app-netshift/po/ru/netshift.po

@@ -7,8 +7,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: NETSHIFT\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-06-02 17:15+0300\n"
-"PO-Revision-Date: 2026-06-02 17:15+0300\n"
+"POT-Creation-Date: 2026-06-06 00:53+0300\n"
+"PO-Revision-Date: 2026-06-06 00:53+0300\n"
 "Last-Translator: yandexru45\n"
 "Language-Team: none\n"
 "Language: ru\n"
@@ -29,18 +29,18 @@ msgstr "✘ Отключено"
 msgid "✘ Stopped"
 msgstr "✘ Остановлен"
 
-msgid "Группировать по странам"
-msgstr ""
-
-msgid "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"
-msgstr ""
-
 msgid "Active Connections"
 msgstr "Активные соединения"
 
 msgid "Additional marking rules found"
 msgstr "Найдены дополнительные правила маркировки"
 
+msgid "Affects Cloudflare, Google, Quad9, OpenDNS, AdGuard, and Yandex public DoH servers."
+msgstr "Затрагивает публичные DoH-серверы Cloudflare, Google, Quad9, OpenDNS, AdGuard и Yandex."
+
+msgid "Allow insecure TLS for subscription fetch"
+msgstr "Разрешить небезопасный TLS при загрузке подписки"
+
 msgid "Allows access to YACD from the WAN. Make sure to open the appropriate port in your firewall."
 msgstr "Обеспечивает доступ к YACD из WAN. Убедитесь, что в брандмауэре открыт соответствующий порт."
 
@@ -56,6 +56,12 @@ msgstr "Необходимо указать хотя бы одну действ
 msgid "Available actions"
 msgstr "Доступные действия"
 
+msgid "Block direct connections to known public DNS-over-HTTPS (DoH) servers."
+msgstr "Блокирует прямые подключения к известным публичным серверам DNS-over-HTTPS (DoH)."
+
+msgid "Block DoH Servers"
+msgstr "Блокировать DoH-серверы"
+
 msgid "Bootsrap DNS"
 msgstr "Bootstrap DNS"
 
@@ -77,6 +83,9 @@ msgstr "Путь к файлу кэша не может быть пустым"
 msgid "Cannot receive checks result"
 msgstr "Не удалось получить результаты проверки"
 
+msgid "Check update"
+msgstr "Проверить обновление"
+
 msgid "Checking, please wait"
 msgstr "Проверяем, пожалуйста подождите"
 
@@ -98,11 +107,14 @@ msgstr "Закрыть"
 msgid "Community Lists"
 msgstr "Списки сообщества"
 
+msgid "Component Manager"
+msgstr "Менеджер компонентов"
+
 msgid "Config File Path"
 msgstr "Путь к файлу конфигурации"
 
 msgid "Configuration for NetShift service"
-msgstr ""
+msgstr "Конфигурация службы NetShift"
 
 msgid "Configuration Type"
 msgstr "Тип конфигурации"
@@ -116,6 +128,12 @@ msgstr "URL подключения"
 msgid "Copy"
 msgstr "Копировать"
 
+msgid "Core switch failed"
+msgstr "Не удалось переключить ядро"
+
+msgid "Core switch timed out"
+msgstr "Истекло время ожидания переключения ядра"
+
 msgid "Currently unavailable"
 msgstr "Временно недоступно"
 
@@ -126,11 +144,14 @@ msgid "Dashboard currently unavailable"
 msgstr "Дашборд сейчас недоступен"
 
 msgid "Delay in milliseconds before reloading NetShift after interface UP"
-msgstr ""
+msgstr "Задержка в миллисекундах перед перезагрузкой NetShift после поднятия интерфейса"
 
 msgid "Delay value cannot be empty"
 msgstr "Значение задержки не может быть пустым"
 
+msgid "Dev"
+msgstr "Dev"
+
 msgid "DHCP has DNS server"
 msgstr "DHCP содержит DNS сервер"
 
@@ -149,9 +170,15 @@ msgstr "Отключить QUIC протокол для улучшения со
 msgid "Disabled"
 msgstr "Отключено"
 
+msgid "Disables TLS certificate verification when downloading the subscription."
+msgstr "Отключает проверку TLS-сертификата при загрузке подписки."
+
 msgid "DNS on router"
 msgstr "DNS на роутере"
 
+msgid "DNS outbound section"
+msgstr "Секция outbound для DNS"
+
 msgid "DNS over HTTPS (DoH)"
 msgstr "DNS через HTTPS (DoH)"
 
@@ -194,6 +221,9 @@ msgstr "Скачивать списки через выбранную секци
 msgid "Downloading all lists via specific Proxy/VPN"
 msgstr "Загрузка всех списков через указанный прокси/VPN"
 
+msgid "Drop subscription servers whose name contains any of these keywords (case-insensitive)."
+msgstr "Исключать серверы подписки, имя которых содержит любое из этих ключевых слов (без учёта регистра)."
+
 msgid "Dynamic List"
 msgstr "Динамический список"
 
@@ -206,6 +236,12 @@ msgstr "Включить встроенный DNS-резолвер для дом
 msgid "Enable DNS resolve to get real IP when routing"
 msgstr "Разрешать домены в реальные IP-адреса перед маршрутизацией в outbound"
 
+msgid "Enable IPv6 Support"
+msgstr "Включить поддержку IPv6"
+
+msgid "Enable IPv6 TProxy routing, IPv6 DNS inbound, and IPv6 FakeIP support."
+msgstr "Включить маршрутизацию TProxy по IPv6, входящий DNS по IPv6 и поддержку FakeIP для IPv6."
+
 msgid "Enable Mixed Proxy"
 msgstr "Включить смешанный прокси"
 
@@ -234,22 +270,22 @@ msgid "Enter subnets in CIDR notation (e.g. 103.21.244.0/22) or single IP addres
 msgstr "Введите подсети в нотации CIDR (например, 103.21.244.0/22) или отдельные IP-адреса"
 
 msgid "Enter the subscription URL to fetch proxy configurations from your provider"
-msgstr ""
+msgstr "Введите URL подписки для получения конфигураций прокси от вашего провайдера"
 
 msgid "Every 1 minute"
 msgstr "Каждую минуту"
 
 msgid "Every 12 hours"
-msgstr ""
+msgstr "Каждые 12 часов"
 
 msgid "Every 3 hours"
-msgstr ""
+msgstr "Каждые 3 часа"
 
 msgid "Every 3 minutes"
 msgstr "Каждые 3 минуты"
 
 msgid "Every 30 minutes"
-msgstr ""
+msgstr "Каждые 30 минут"
 
 msgid "Every 30 seconds"
 msgstr "Каждые 30 секунд"
@@ -258,13 +294,13 @@ msgid "Every 5 minutes"
 msgstr "Каждые 5 минут"
 
 msgid "Every 6 hours"
-msgstr ""
+msgstr "Каждые 6 часов"
 
 msgid "Every day"
-msgstr ""
+msgstr "Каждый день"
 
 msgid "Every hour"
-msgstr ""
+msgstr "Каждый час"
 
 msgid "Exclude NTP"
 msgstr "Исключить NTP"
@@ -272,6 +308,9 @@ msgstr "Исключить NTP"
 msgid "Exclude NTP protocol traffic from the tunnel to prevent it from being routed through the proxy or VPN"
 msgstr "Исключите трафик протокола NTP из туннеля, чтобы предотвратить его маршрутизацию через прокси-сервер или VPN."
 
+msgid "Exclude servers by keyword"
+msgstr "Исключать серверы по ключевому слову"
+
 msgid "Failed to copy!"
 msgstr "Не удалось скопировать!"
 
@@ -290,17 +329,23 @@ msgstr "Получить глобальную проверку"
 msgid "Global check"
 msgstr "Глобальная проверка"
 
+msgid "Global Proxy"
+msgstr "Глобальный прокси"
+
 msgid "How often to automatically update the subscription"
-msgstr ""
+msgstr "Как часто автоматически обновлять подписку"
 
 msgid "HTTP error"
 msgstr "Ошибка HTTP"
 
-msgid "Install extended"
-msgstr "Установить extended"
+msgid "Include servers by keyword"
+msgstr "Включать серверы по ключевому слову"
 
-msgid "Install stable"
-msgstr "Установить stable"
+msgid "Install %s"
+msgstr "Установить %s"
+
+msgid "Installed version is newer than release"
+msgstr "Установленная версия новее релиза"
 
 msgid "Interface Monitoring"
 msgstr "Мониторинг интерфейса"
@@ -311,14 +356,14 @@ msgstr "Задержка при мониторинге интерфейсов"
 msgid "Interface monitoring for Bad WAN"
 msgstr "Мониторинг интерфейса для Bad WAN"
 
-msgid "Invalid DNS server format. Examples: 8.8.8.8 or dns.example.com or dns.example.com/nicedns for DoH"
-msgstr "Неверный формат DNS-сервера. Примеры: 8.8.8.8, dns.example.com или dns.example.com/nicedns для DoH"
+msgid "Invalid DNS server format. Examples: 8.8.8.8, [::1], dns.example.com, or dns.example.com/dns-query for DoH"
+msgstr "Неверный формат DNS-сервера. Примеры: 8.8.8.8, [::1], dns.example.com или dns.example.com/dns-query для DoH"
 
 msgid "Invalid domain address"
 msgstr "Неверный домен"
 
-msgid "Invalid format. Use X.X.X.X or X.X.X.X/Y"
-msgstr "Неверный формат. Используйте X.X.X.X или X.X.X.X/Y"
+msgid "Invalid format. Use X.X.X.X/Y or IPv6/Y"
+msgstr "Неверный формат. Используйте X.X.X.X/Y или IPv6/Y"
 
 msgid "Invalid HY2 URL: insecure must be 0 or 1"
 msgstr "Неверный URL Hysteria2: параметр insecure должен быть 0 или 1"
@@ -362,6 +407,9 @@ msgstr "Неверный URL Hysteria2: неподдерживаемый тип
 msgid "Invalid IP address"
 msgstr "Неверный IP-адрес"
 
+msgid "Invalid IPv6 address"
+msgstr "Неверный IPv6-адрес"
+
 msgid "Invalid JSON format"
 msgstr "Неверный формат JSON"
 
@@ -440,15 +488,48 @@ msgstr "Неверный формат URL"
 msgid "Invalid VLESS URL: parsing failed"
 msgstr "Неверный URL VLESS: ошибка разбора"
 
+msgid "Invalid VMess URL: invalid port"
+msgstr "Неверный URL VMess: недопустимый порт"
+
+msgid "Invalid VMess URL: malformed base64"
+msgstr "Неверный URL VMess: некорректный base64"
+
+msgid "Invalid VMess URL: malformed JSON"
+msgstr "Неверный URL VMess: некорректный JSON"
+
+msgid "Invalid VMess URL: missing address"
+msgstr "Неверный URL VMess: отсутствует адрес"
+
+msgid "Invalid VMess URL: missing id"
+msgstr "Неверный URL VMess: отсутствует id"
+
+msgid "Invalid VMess URL: must not contain spaces"
+msgstr "Неверный URL VMess: не должен содержать пробелы"
+
+msgid "Invalid VMess URL: must start with vmess://"
+msgstr "Неверный URL VMess: должен начинаться с vmess://"
+
 msgid "IP address 0.0.0.0 is not allowed"
 msgstr "IP-адрес 0.0.0.0 не допускается"
 
+msgid "IPv6 CIDR must be between 0 and 128"
+msgstr "IPv6 CIDR должен быть от 0 до 128"
+
 msgid "Issues detected"
 msgstr "Обнаружены проблемы"
 
+msgid "Keep only subscription servers whose name contains at least one of these keywords (case-insensitive). Leave empty to keep all."
+msgstr "Оставлять только серверы подписки, имя которых содержит хотя бы одно из этих ключевых слов (без учёта регистра). Оставьте пустым, чтобы оставить все."
+
 msgid "Latest"
 msgstr "Последняя"
 
+msgid "Latest version is installed"
+msgstr "Установлена последняя версия"
+
+msgid "Latest version is unknown"
+msgstr "Последняя версия неизвестна"
+
 msgid "List Update Frequency"
 msgstr "Частота обновления списков"
 
@@ -464,6 +545,9 @@ msgstr "Уровень логов"
 msgid "Main DNS"
 msgstr "Основной DNS"
 
+msgid "Main DNS via outbound"
+msgstr "Основной DNS через outbound"
+
 msgid "Memory Usage"
 msgstr "Использование памяти"
 
@@ -477,13 +561,16 @@ msgid "Must be a number in the range of 50 - 1000"
 msgstr "Должно быть числом от 50 до 1000"
 
 msgid "NetShift"
-msgstr ""
+msgstr "NetShift"
 
 msgid "NetShift Settings"
-msgstr ""
+msgstr "Настройки NetShift"
+
+msgid "NetShift updated, version:"
+msgstr "NetShift обновлён, версия:"
 
 msgid "NetShift will not modify your DHCP configuration"
-msgstr ""
+msgstr "NetShift не будет изменять вашу конфигурацию DHCP"
 
 msgid "Network Interface"
 msgstr "Сетевой интерфейс"
@@ -494,12 +581,21 @@ msgstr "Другие правила маркировки не найдены"
 msgid "Not implement yet"
 msgstr "Ещё не реализовано"
 
+msgid "Not installed"
+msgstr "Не установлено"
+
 msgid "Not responding"
 msgstr "Не отвечает"
 
 msgid "Not running"
 msgstr "Не запущено"
 
+msgid "Note: if your upstream DNS type is set to 'DoH', enable this only after switching to UDP or DoT."
+msgstr "Примечание: если тип вышестоящего DNS установлен в «DoH», включайте это только после переключения на UDP или DoT."
+
+msgid "Only one section can be global at a time."
+msgstr "Только одна секция может быть глобальной одновременно."
+
 msgid "Operation timed out"
 msgstr "Время ожидания истекло"
 
@@ -552,7 +648,13 @@ msgid "Resolve real IP for routing"
 msgstr "Разрешение реальных IP-адресов"
 
 msgid "Restart NetShift"
-msgstr ""
+msgstr "Перезапустить NetShift"
+
+msgid "Route all unmatched traffic through this section's outbound."
+msgstr "Направлять весь несовпавший трафик через outbound этой секции."
+
+msgid "Route main DNS through proxy/VPN"
+msgstr "Основной DNS через прокси/VPN"
 
 msgid "Router DNS is not routed through sing-box"
 msgstr "DNS роутера не проходит через sing-box"
@@ -569,9 +671,6 @@ msgstr "Счётчики правил mangle"
 msgid "Rules mangle exist"
 msgstr "Правила mangle существуют"
 
-msgid "Rules mangle output counters"
-msgstr "Счётчики правил mangle output"
-
 msgid "Rules mangle output exist"
 msgstr "Правила mangle output существуют"
 
@@ -647,6 +746,12 @@ msgstr "Selector"
 msgid "Selector Proxy Links"
 msgstr "Ссылки прокси для Selector"
 
+msgid "Self-update failed"
+msgstr "Не удалось обновить"
+
+msgid "Send upstream DNS queries through a proxy/VPN outbound instead of directly. Bootstrap DNS always stays direct."
+msgstr "Отправлять запросы к основному DNS через outbound прокси/VPN вместо прямого подключения. Bootstrap DNS всегда остаётся прямым."
+
 msgid "Services info"
 msgstr "Информация о сервисах"
 
@@ -699,23 +804,32 @@ msgid "Specify the path to the list file located on the router filesystem"
 msgstr "Укажите путь к файлу списка, расположенному в файловой системе маршрутизатора."
 
 msgid "Start NetShift"
-msgstr ""
+msgstr "Запустить NetShift"
 
 msgid "Stop NetShift"
-msgstr ""
+msgstr "Остановить NetShift"
 
 msgid "Subscription"
-msgstr ""
+msgstr "Подписка"
 
 msgid "Subscription Update Interval"
-msgstr ""
+msgstr "Интервал обновления подписки"
 
 msgid "Subscription URL"
-msgstr ""
+msgstr "URL подписки"
 
 msgid "Successfully copied!"
 msgstr "Успешно скопировано!"
 
+msgid "Switch to extended"
+msgstr "Переключить на extended"
+
+msgid "Switch to stable"
+msgstr "Переключить на stable"
+
+msgid "Switching sing-box core, this may take a few minutes…"
+msgstr "Переключение ядра sing-box, это может занять несколько минут…"
+
 msgid "System info"
 msgstr "Системная информация"
 
@@ -743,6 +857,12 @@ msgstr "Максимально допустимая разница во врем
 msgid "The URL used to test server connectivity"
 msgstr "URL-адрес, используемый для проверки подключения к серверу"
 
+msgid "This is a security trade-off: an attacker could intercept the fetch."
+msgstr "Это компромисс в безопасности: злоумышленник может перехватить загрузку."
+
+msgid "This prevents applications from bypassing the router's DNS filtering by using their own encrypted DNS."
+msgstr "Это не позволяет приложениям обходить DNS-фильтрацию роутера за счёт использования собственного шифрованного DNS."
+
 msgid "Time in seconds for DNS record caching (default: 60)"
 msgstr "Время в секундах для кэширования DNS записей (по умолчанию: 60)"
 
@@ -773,11 +893,23 @@ msgstr "неизвестно"
 msgid "Unknown error"
 msgstr "Неизвестная ошибка"
 
+msgid "Update"
+msgstr "Обновить"
+
+msgid "Update is available"
+msgstr "Доступно обновление"
+
+msgid "Update NetShift"
+msgstr "Обновить NetShift"
+
+msgid "Updating NetShift, this may take a few minutes; the page will reload…"
+msgstr "Обновление NetShift, это может занять несколько минут; страница перезагрузится…"
+
 msgid "Uplink"
 msgstr "Исходящий"
 
-msgid "URL must start with vless://, ss://, trojan://, socks4/5://, or hysteria2://hy2://"
-msgstr "URL должен начинаться с vless://, ss://, trojan://, socks4/5:// или hysteria2:// hy2://"
+msgid "URL must start with vless://, vmess://, ss://, trojan://, socks4/5://, or hysteria2://hy2://"
+msgstr "URL должен начинаться с vless://, vmess://, ss://, trojan://, socks4/5:// или hysteria2:// hy2://"
 
 msgid "URL must use one of the following protocols:"
 msgstr "URL должен использовать один из следующих протоколов:"
@@ -797,6 +929,15 @@ msgstr "URLTest ссылка для проверки"
 msgid "URLTest Tolerance"
 msgstr "URLTest допустимое отклонение"
 
+msgid "Use only for IP-host panels that serve an invalid or self-signed certificate."
+msgstr "Используйте только для панелей с IP-адресом, у которых недействительный или самоподписанный сертификат."
+
+msgid "Use this only when the router has working IPv6 connectivity."
+msgstr "Используйте это только если на роутере есть рабочее подключение по IPv6."
+
+msgid "Use with Exclusion sections to route specific domains directly."
+msgstr "Используйте вместе с секциями исключений для прямой маршрутизации определённых доменов."
+
 msgid "User Domain List Type"
 msgstr "Тип пользовательского списка доменов"
 
@@ -821,14 +962,17 @@ msgstr "Валидно"
 msgid "Validation errors:"
 msgstr "Ошибки валидации:"
 
+msgid "Version"
+msgstr "Версия"
+
 msgid "View logs"
 msgstr "Посмотреть логи"
 
 msgid "Visit Wiki"
 msgstr "Перейти в wiki"
 
-msgid "vless://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links"
-msgstr ""
+msgid "vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2:// links"
+msgstr "ссылки vless://, vmess://, ss://, trojan://, socks4/5://, hy2/hysteria2://"
 
 msgid "Warning: %s cannot be used together with %s. Previous selections have been removed."
 msgstr "Предупреждение: %s нельзя использовать вместе с %s. Предыдущие варианты были удалены."
@@ -836,8 +980,20 @@ msgstr "Предупреждение: %s нельзя использовать
 msgid "Warning: Russia inside can only be used with %s. %s already in Russia inside and have been removed from selection."
 msgstr "Предупреждение: Russia inside может быть использован только с %s. %s уже есть в Russia inside и будет удален из выбранных."
 
+msgid "When enabled, traffic not matching any other section's lists will go through this proxy."
+msgstr "Когда включено, трафик, не совпадающий со списками других секций, будет идти через этот прокси."
+
+msgid "Which proxy/VPN section carries the DNS. Leave unset to use the first configured outbound."
+msgstr "Какая секция прокси/VPN обслуживает DNS. Оставьте пустым, чтобы использовать первый настроенный outbound."
+
 msgid "YACD Secret Key"
 msgstr "Секретный ключ YACD"
 
 msgid "You can select Output Network Interface, by default autodetect"
 msgstr "Вы можете выбрать выходной сетевой интерфейс, по умолчанию он определяется автоматически."
+
+msgid "Группировать по странам"
+msgstr "Группировать по странам"
+
+msgid "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"
+msgstr "Группирует прокси подписки по флагу страны в начале тега в отдельные URLTest-группы"

netshift/files/etc/config/netshift

@@ -13,12 +13,16 @@ config settings 'settings'
         option disable_quic '0'
         option update_interval '1d'
         option download_lists_via_proxy '0'
+        #option dns_via_outbound '0'
+        #option dns_outbound_section 'main'
         option dont_touch_dhcp '0'
         option config_path '/etc/sing-box/config.json'
         option cache_path '/tmp/sing-box/cache.db'
         option log_level 'warn'
         option exclude_ntp '0'
         option shutdown_correctly '0'
+        option block_doh '0'
+        option enable_ipv6 '0'
         #list routing_excluded_ips '192.168.1.3'
 
 config section 'main'
@@ -26,6 +30,7 @@ config section 'main'
         option proxy_config_type 'url'
         option proxy_string ''
         option enable_udp_over_tcp '0'
+        option global_proxy '0'
         list community_lists 'russia_inside'
         #option user_domain_list_type 'dynamic'
         #list user_domains '2ip.ru'
@@ -43,9 +48,20 @@ config section 'main'
 #        option connection_type 'proxy'
 #        option proxy_config_type 'subscription'
 #        option subscription_url 'https://example.com/api/sub'
+#        # Allow insecure TLS for the subscription fetch (default 0). Set to 1 to
+#        # add wget --no-check-certificate for IP-host panels whose HTTPS cert is
+#        # invalid/self-signed/missing-SAN. Disables certificate verification.
+#        #option subscription_insecure '0'
 #        option subscription_update_interval '1h'
 #        #option subscription_group_by_countries '0'
 #        #option urltest_check_interval '3m'
 #        #option urltest_tolerance '50'
 #        #option urltest_testing_url 'https://www.gstatic.com/generate_204'
+#        # Keyword whitelist: keep only nodes whose display name contains any of
+#        # these (OR). Empty/absent = keep all. Substring, ASCII case-insensitive.
+#        #list subscription_filter_include_keywords '🤖'
+#        #list subscription_filter_include_keywords 'grpc'
+#        # Keyword blacklist: drop any node whose display name contains any of
+#        # these (OR). Empty/absent = no exclusion.
+#        #list subscription_filter_exclude_keywords 'expired'
 #        list community_lists 'russia_inside'

netshift/files/usr/lib/constants.sh

@@ -14,6 +14,14 @@ TMP_RULESET_FOLDER="$TMP_SING_BOX_FOLDER/rulesets"
 TMP_SUBSCRIPTION_FOLDER="$TMP_SING_BOX_FOLDER/subscriptions"
 SUBSCRIPTION_CACHE_FOLDER="$NETSHIFT_STATE_DIR/subscriptions"
 TMP_SUBSCRIPTION_DOWNLOAD_FOLDER="$TMP_SING_BOX_FOLDER/subscription-downloads"
+# Subscription User-Agent fallback. Many panels return a DIFFERENT body format
+# depending on the client User-Agent (sing-box JSON vs base64 URI list vs Clash
+# vs Xray JSON, or an HTML/403 stub for unknown clients). When no User-Agent is
+# configured for a source, the backend tries these candidates in order and
+# keeps the first one that yields valid sing-box outbounds. The default
+# "singbox/<version>" candidate is prepended at runtime (it depends on the
+# installed sing-box). Order matters: most-likely-to-work first.
+SUBSCRIPTION_USER_AGENT_CANDIDATES="v2rayN Happ Hiddify Clash.Meta ClashMetaForAndroid"
 CLOUDFLARE_OCTETS="8.47 162.159 188.114" # Endpoints https://github.com/ampetelin/warp-endpoint-checker
 JQ_REQUIRED_VERSION="1.7.1"
 COREUTILS_BASE64_REQUIRED_VERSION="9.7"
@@ -22,7 +30,7 @@ RT_TABLE_NAME="netshift"
 ## nft
 NFT_TABLE_NAME="NetShiftTable"
 NFT_LOCALV4_SET_NAME="localv4"
-NFT_COMMON_SET_NAME="netshift_subnets"
+NFT_LOCALV6_SET_NAME="localv6"
 NFT_DISCORD_SET_NAME="netshift_discord_subnets"
 NFT_INTERFACE_SET_NAME="interfaces"
 NFT_FAKEIP_MARK="0x00100000"
@@ -30,10 +38,46 @@ NFT_OUTBOUND_MARK="0x00200000"
 
 ## sing-box
 SB_REQUIRED_VERSION="1.12.0"
+# Monitoring
+MONITOR_CHECK_INTERVAL=10
+MONITOR_MAX_CRASHES=5
+MONITOR_BACKOFF_BASE=10
+MONITOR_BACKOFF_MAX=300
+# Core-switch connectivity self-heal (task-009). Hosts probed before a core
+# swap, depending on direction: the stable (stock) install pulls from the
+# OpenWrt package feeds, the extended install pulls from the GitHub API.
+UPDATES_FEED_PROBE_HOST="downloads.openwrt.org"
+UPDATES_GITHUB_PROBE_HOST="api.github.com"
+# Temporary public resolvers written to /etc/resolv.conf when DNS healing is
+# needed (the user's upstream may itself be the now-dead VPN).
+UPDATES_HEAL_RESOLVERS="1.1.1.1 9.9.9.9"
+# tmpfs backup path for the original /etc/resolv.conf during a heal.
+UPDATES_RESOLV_BACKUP="/tmp/netshift-resolv.conf.bak"
+# Installed core paths (indirected so the stable backup/rollback path is unit
+# testable without clobbering the real binary). These are the real on-device
+# locations; tests override them.
+UPDATES_SING_BOX_BIN="/usr/bin/sing-box"
+UPDATES_LIBCRONET_LIB="/usr/lib/libcronet.so"
+# Component Manager — NetShift self-update (task-017). The GitHub latest-release
+# API for NetShift itself (same endpoint install.sh and get_system_info use);
+# the self-update worker downloads the release .ipk/.apk assets from it.
+NETSHIFT_RELEASE_API_URL="https://api.github.com/repos/yandexru45/netshift/releases/latest"
+# tmpfs scratch dir for the self-update download (release packages) — RAM, never
+# the tiny overlay; reaped on success and on reboot.
+UPDATES_NETSHIFT_DOWNLOAD_DIR="/tmp/netshift/selfupdate"
+# tmpfs backup of /etc/config/netshift taken before the self-update package
+# install (conffiles normally preserve it; this is the defensive belt).
+UPDATES_NETSHIFT_CONFIG_BACKUP="/tmp/netshift/config.bak"
+# NetShift package names handled by the self-update (in install order). The RU
+# i18n package is upgraded ONLY if already installed (never newly installed).
+UPDATES_NETSHIFT_PKG_CORE="netshift"
+UPDATES_NETSHIFT_PKG_LUCI="luci-app-netshift"
+UPDATES_NETSHIFT_PKG_I18N_RU="luci-i18n-netshift-ru"
 # DNS
 SB_DNS_SERVER_TAG="dns-server"
 SB_FAKEIP_DNS_SERVER_TAG="fakeip-server"
 SB_FAKEIP_INET4_RANGE="198.18.0.0/15"
+SB_FAKEIP_INET6_RANGE="fd00:ec3a::/32"
 SB_BOOTSTRAP_SERVER_TAG="bootstrap-dns-server"
 SB_FAKEIP_DNS_RULE_TAG="fakeip-dns-rule-tag"
 SB_INVERT_FAKEIP_DNS_RULE_TAG="invert-fakeip-dns-rule-tag"
@@ -41,9 +85,13 @@ SB_INVERT_FAKEIP_DNS_RULE_TAG="invert-fakeip-dns-rule-tag"
 SB_TPROXY_INBOUND_TAG="tproxy-in"
 SB_TPROXY_INBOUND_ADDRESS="127.0.0.1"
 SB_TPROXY_INBOUND_PORT=1602
+SB_TPROXY_INBOUND_ADDRESS_V6="::1"
+SB_TPROXY_INBOUND_PORT_V6=1603
 SB_DNS_INBOUND_TAG="dns-in"
 SB_DNS_INBOUND_ADDRESS="127.0.0.42"
 SB_DNS_INBOUND_PORT=53
+SB_DNS_INBOUND_ADDRESS_V6="::1"
+SB_DNS_INBOUND_PORT_V6=5354
 SB_SERVICE_MIXED_INBOUND_TAG="service-mixed-in"
 SB_SERVICE_MIXED_INBOUND_ADDRESS="127.0.0.1"
 SB_SERVICE_MIXED_INBOUND_PORT=4534
@@ -52,9 +100,14 @@ SB_DIRECT_OUTBOUND_TAG="direct-out"
 # Route
 SB_REJECT_RULE_TAG="reject-rule-tag"
 SB_EXCLUSION_RULE_TAG="exclusion-rule-tag"
+SB_DOH_BLOCK_RULE_TAG="doh-block-rule-tag"
 # Experimental
 SB_CLASH_API_CONTROLLER_PORT=9090
 
+## DoH blocking
+DOH_BLOCK_IPV4_CIDRS="1.1.1.1/32 1.0.0.1/32 8.8.8.8/32 8.8.4.4/32 9.9.9.9/32 9.9.9.11/32 149.112.112.112/32 208.67.222.222/32 208.67.220.220/32 94.140.14.14/32 94.140.15.15/32 77.88.8.8/32 77.88.8.1/32"
+DOH_BLOCK_IPV6_CIDRS="2606:4700:4700::1111/128 2606:4700:4700::1001/128 2001:4860:4860::8888/128 2001:4860:4860::8844/128 2620:fe::fe/128 2620:fe::9/128 2620:119:35::35/128 2620:119:53::53/128 2a10:50c0::ad1:ff/128 2a10:50c0::ad2:ff/128 2a02:6b8::feed:0ff/128 2a02:6b8:0:1::feed:0ff/128"
+
 ## Lists
 GITHUB_RAW_URL="https://raw.githubusercontent.com/itdoginfo/allow-domains/main"
 SRS_MAIN_URL="https://github.com/itdoginfo/allow-domains/releases/latest/download"

netshift/files/usr/lib/helpers.sh

@@ -147,7 +147,11 @@ url_get_host() {
     url="${url#*@}"
     url="${url%%[/?#]*}"
 
-    echo "${url%%:*}"
+    case "$url" in
+    \[*\]) echo "${url#\[}" | sed 's/\]$//' ;;
+    \[*\]*) echo "${url#\[}" | sed 's/\].*//' ;;
+    *) echo "${url%%:*}" ;;
+    esac
 }
 
 # Extracts the port number from a URL
@@ -159,6 +163,7 @@ url_get_port() {
     url="${url%%[/?#]*}"
 
     case "$url" in
+    \[*\]:*) echo "${url##*]:}" ;;
     *:*) echo "${url#*:}" ;;
     *) echo "" ;;
     esac
@@ -221,6 +226,47 @@ base64_decode() {
     echo "$decoded_url"
 }
 
+# Decodes a vmess:// share link (V2RayN base64(JSON) form) into its JSON object.
+# Strips the vmess:// scheme prefix, base64-decodes the remainder, and echoes the
+# decoded text (expected to be a JSON object; the caller validates with jq -e).
+# Returns empty output when the input is not a base64(JSON) VMess link.
+#
+# IMPORTANT: this decodes the WHOLE payload as STANDARD base64 (alphabet
+# includes '+'), so the caller MUST pass the RAW pre-url_decode link — passing a
+# url_decode'd link rewrites '+'->space and corrupts the body.
+# Arguments:
+#   $1 - the vmess:// link (raw, pre-url_decode)
+vmess_link_to_json() {
+    local url="$1"
+    local payload decoded pad_len
+
+    payload="${url#vmess://}"
+    # Strip a trailing '#fragment' (server display name / remark, like vless/ss/
+    # trojan). The base64 body never contains '#', so cutting at the FIRST '#'
+    # is safe; a fragment-less payload is a no-op. The canonical VMess name lives
+    # in the decoded JSON `ps` field, so we only need to drop the fragment here.
+    payload="${payload%%#*}"
+    [ -n "$payload" ] || return 0
+
+    # Normalize: strip whitespace (space, tab, CR, LF via octal escapes — busybox
+    # `tr` does NOT understand the POSIX `[:space:]` class and would instead
+    # delete those literal characters, corrupting the base64), then right-pad to
+    # a multiple of 4 with '=' so BusyBox `base64 -d` (which can reject missing
+    # padding) accepts real-world unpadded links.
+    payload="$(printf '%s' "$payload" | tr -d ' \011\012\015')"
+    pad_len=$(( ${#payload} % 4 ))
+    if [ "$pad_len" -ne 0 ]; then
+        pad_len=$(( 4 - pad_len ))
+        while [ "$pad_len" -gt 0 ]; do
+            payload="${payload}="
+            pad_len=$(( pad_len - 1 ))
+        done
+    fi
+
+    decoded="$(base64_decode "$payload")"
+    echo "$decoded"
+}
+
 # Generates a unique 16-character ID based on the current timestamp and a random number
 gen_id() {
     { date +%s; head -c 16 /dev/urandom; } | md5sum | cut -c1-16
@@ -660,13 +706,109 @@ generate_hwid() {
         "$(echo "$raw_hash" | cut -c13-16)"
 }
 
-# Downloads a subscription JSON from the given URL with custom headers
+# Resolves the effective subscription User-Agent: the explicit value when one
+# is given, otherwise the default "singbox/<version>" string. Centralizes the
+# default so download_subscription and the candidate builder agree.
+get_subscription_user_agent() {
+    local custom_user_agent="${1:-}"
+
+    if [ -n "$custom_user_agent" ]; then
+        printf '%s' "$custom_user_agent"
+        return 0
+    fi
+
+    printf 'singbox/%s' "$(get_sing_box_version)"
+}
+
+# Emits the ordered, de-duplicated list of User-Agent candidates (one per line)
+# to try for a subscription source when no User-Agent is explicitly configured.
+# Different panels key the returned body format off the User-Agent, so we probe
+# a whitelist of well-known clients and let the caller keep the first that
+# yields valid outbounds.
+#
+# Arguments:
+#   $1 - configured User-Agent (empty for auto mode)
+#   $2 - preferred User-Agent (e.g. the previously cached winner; tried early)
+# Behavior:
+#   - configured non-empty: emit ONLY that value (respect the user's choice).
+#   - auto: emit "singbox/<ver>", then the preferred one, then the whitelist
+#     from constants (SUBSCRIPTION_USER_AGENT_CANDIDATES), skipping duplicates.
+build_subscription_user_agent_candidates() {
+    local configured_user_agent="${1:-}"
+    local preferred_user_agent="${2:-}"
+    local default_user_agent candidate seen
+
+    if [ -n "$configured_user_agent" ]; then
+        printf '%s\n' "$configured_user_agent"
+        return 0
+    fi
+
+    default_user_agent="$(get_subscription_user_agent)"
+    seen=""
+    # shellcheck disable=SC2086 # word-splitting of the candidate list is intentional
+    for candidate in "$default_user_agent" "$preferred_user_agent" $SUBSCRIPTION_USER_AGENT_CANDIDATES; do
+        [ -n "$candidate" ] || continue
+        # Skip a candidate already emitted. Wrap stored names in newlines so the
+        # substring test matches whole entries only.
+        case "$seen" in
+        *"
+$candidate
+"*) continue ;;
+        esac
+        seen="${seen}
+$candidate
+"
+        printf '%s\n' "$candidate"
+    done
+}
+
+# Runs a single wget subscription request with the shared client-mimicking
+# headers and an optional --no-check-certificate flag, so all branches of
+# download_subscription stay byte-identical.
+# Arguments:
+#   $1       - cert flag ("" or "--no-check-certificate")
+#   $2       - User-Agent header value
+#   $3       - X-HWID header value
+#   $4       - X-Device-Model header value
+#   $5       - X-Ver-OS header value
+#   $6       - output file path (passed to wget -O)
+#   $7       - error file path (wget stderr is redirected here)
+#   $8       - subscription URL
+#   $9..     - leading wget flags (e.g. -4, -T, <timeout>)
+# Caller is responsible for exporting http_proxy/https_proxy when needed.
+_wget_subscription_request() {
+    local cert_flag="$1"
+    local req_user_agent="$2"
+    local req_hwid="$3"
+    local req_device_model="$4"
+    local req_kernel_version="$5"
+    local req_outfile="$6"
+    local req_errfile="$7"
+    local req_url="$8"
+    shift 8
+
+    # shellcheck disable=SC2086
+    wget $cert_flag "$@" -O "$req_outfile" \
+        --header "User-Agent: $req_user_agent" \
+        --header "X-HWID: $req_hwid" \
+        --header "X-Device-OS: OpenWrt Linux" \
+        --header "X-Device-Model: $req_device_model" \
+        --header "X-Ver-OS: $req_kernel_version" \
+        --header "Accept-Language: ru-RU,en,*" \
+        --header "X-Device-Locale: EN" \
+        "$req_url" 2>"$req_errfile"
+}
+
+# Downloads a subscription body from the given URL with client-mimicking headers
 # Arguments:
 #   $1 - subscription URL
 #   $2 - output file path
 #   $3 - http proxy address (optional)
 #   $4 - retries (optional, default 3)
 #   $5 - wait between retries (optional, default 2)
+#   $6 - timeout seconds (optional, default 10)
+#   $7 - User-Agent (optional; default "singbox/<version>")
+#   $8 - insecure (optional, default 0; when 1 adds --no-check-certificate)
 download_subscription() {
     local url="$1"
     local filepath="$2"
@@ -674,12 +816,23 @@ download_subscription() {
     local retries="${4:-3}"
     local wait="${5:-2}"
     local timeout="${6:-10}"
+    local user_agent="${7:-}"
+    local insecure="${8:-0}"
 
     local sb_version device_model kernel_version hwid
     sb_version="$(get_sing_box_version)"
     device_model="$(get_device_model)"
     kernel_version="$(get_kernel_version)"
     hwid="$(generate_hwid)"
+    [ -n "$user_agent" ] || user_agent="$(get_subscription_user_agent)"
+
+    # Optional TLS-verification bypass for IP-host panels with broken certs.
+    # Empty string keeps the secure default; word-splitting it into the wget
+    # argv (via _wget_subscription_request) yields zero extra args when off.
+    local cert_flag=""
+    if [ "$insecure" = "1" ]; then
+        cert_flag="--no-check-certificate"
+    fi
 
     local tmpfile errfile rc family
     tmpfile="${filepath}.part.$$"
@@ -692,48 +845,24 @@ download_subscription() {
             family="ipv4"
             if [ -n "$http_proxy_address" ]; then
                 http_proxy="http://$http_proxy_address" https_proxy="http://$http_proxy_address" \
-                    wget -4 -T "$timeout" -O "$tmpfile" \
-                        --header "User-Agent: singbox/$sb_version" \
-                        --header "X-HWID: $hwid" \
-                        --header "X-Device-OS: OpenWrt Linux" \
-                        --header "X-Device-Model: $device_model" \
-                        --header "X-Ver-OS: $kernel_version" \
-                        --header "Accept-Language: ru-RU,en,*" \
-                        --header "X-Device-Locale: EN" \
-                        "$url" 2>"$errfile"
+                    _wget_subscription_request "$cert_flag" "$user_agent" "$hwid" \
+                        "$device_model" "$kernel_version" "$tmpfile" "$errfile" "$url" \
+                        -4 -T "$timeout"
             else
-                wget -4 -T "$timeout" -O "$tmpfile" \
-                    --header "User-Agent: singbox/$sb_version" \
-                    --header "X-HWID: $hwid" \
-                    --header "X-Device-OS: OpenWrt Linux" \
-                    --header "X-Device-Model: $device_model" \
-                    --header "X-Ver-OS: $kernel_version" \
-                    --header "Accept-Language: ru-RU,en,*" \
-                    --header "X-Device-Locale: EN" \
-                    "$url" 2>"$errfile"
+                _wget_subscription_request "$cert_flag" "$user_agent" "$hwid" \
+                    "$device_model" "$kernel_version" "$tmpfile" "$errfile" "$url" \
+                    -4 -T "$timeout"
             fi
         else
             if [ -n "$http_proxy_address" ]; then
                 http_proxy="http://$http_proxy_address" https_proxy="http://$http_proxy_address" \
-                    wget -T "$timeout" -O "$tmpfile" \
-                        --header "User-Agent: singbox/$sb_version" \
-                        --header "X-HWID: $hwid" \
-                        --header "X-Device-OS: OpenWrt Linux" \
-                        --header "X-Device-Model: $device_model" \
-                        --header "X-Ver-OS: $kernel_version" \
-                        --header "Accept-Language: ru-RU,en,*" \
-                        --header "X-Device-Locale: EN" \
-                        "$url" 2>"$errfile"
+                    _wget_subscription_request "$cert_flag" "$user_agent" "$hwid" \
+                        "$device_model" "$kernel_version" "$tmpfile" "$errfile" "$url" \
+                        -T "$timeout"
             else
-                wget -T "$timeout" -O "$tmpfile" \
-                    --header "User-Agent: singbox/$sb_version" \
-                    --header "X-HWID: $hwid" \
-                    --header "X-Device-OS: OpenWrt Linux" \
-                    --header "X-Device-Model: $device_model" \
-                    --header "X-Ver-OS: $kernel_version" \
-                    --header "Accept-Language: ru-RU,en,*" \
-                    --header "X-Device-Locale: EN" \
-                    "$url" 2>"$errfile"
+                _wget_subscription_request "$cert_flag" "$user_agent" "$hwid" \
+                    "$device_model" "$kernel_version" "$tmpfile" "$errfile" "$url" \
+                    -T "$timeout"
             fi
         fi
 
@@ -760,25 +889,13 @@ download_subscription() {
             log "Retrying subscription download over IPv4-only" "warn"
             if [ -n "$http_proxy_address" ]; then
                 http_proxy="http://$http_proxy_address" https_proxy="http://$http_proxy_address" \
-                    wget -4 -T "$timeout" -O "$tmpfile" \
-                        --header "User-Agent: singbox/$sb_version" \
-                        --header "X-HWID: $hwid" \
-                        --header "X-Device-OS: OpenWrt Linux" \
-                        --header "X-Device-Model: $device_model" \
-                        --header "X-Ver-OS: $kernel_version" \
-                        --header "Accept-Language: ru-RU,en,*" \
-                        --header "X-Device-Locale: EN" \
-                        "$url" 2>"$errfile"
+                    _wget_subscription_request "$cert_flag" "$user_agent" "$hwid" \
+                        "$device_model" "$kernel_version" "$tmpfile" "$errfile" "$url" \
+                        -4 -T "$timeout"
             else
-                wget -4 -T "$timeout" -O "$tmpfile" \
-                    --header "User-Agent: singbox/$sb_version" \
-                    --header "X-HWID: $hwid" \
-                    --header "X-Device-OS: OpenWrt Linux" \
-                    --header "X-Device-Model: $device_model" \
-                    --header "X-Ver-OS: $kernel_version" \
-                    --header "Accept-Language: ru-RU,en,*" \
-                    --header "X-Device-Locale: EN" \
-                    "$url" 2>"$errfile"
+                _wget_subscription_request "$cert_flag" "$user_agent" "$hwid" \
+                    "$device_model" "$kernel_version" "$tmpfile" "$errfile" "$url" \
+                    -4 -T "$timeout"
             fi
             rc=$?
             if [ "$rc" -eq 0 ] && [ -s "$tmpfile" ]; then
@@ -972,14 +1089,197 @@ describe_subscription_validation_failure() {
     echo "subscription contains no usable proxy outbounds: total=${total:-unknown}, usable=${usable:-unknown}"
 }
 
+# Convert an "Xray JSON" subscription body into a newline-separated list of
+# proxy share URIs (one per line) that the fallback parser's URI loop can
+# consume.
+#
+# An "Xray JSON" body is what several panels (e.g. the Xray/v2rayN ecosystem)
+# hand out instead of a sing-box config: either a single Xray client config
+# object or, more commonly, a JSON ARRAY of such objects. Each object carries
+# an `outbounds` array whose proxy members use the Xray schema
+# (`protocol` + `settings.vnext`/`settings.servers` + `streamSettings`), which
+# is NOT the sing-box outbound schema. validate_subscription_file() rejects it
+# (its outbounds have no sing-box `type`), so without this converter the whole
+# subscription is unusable.
+#
+# Strategy: for every config object we emit one `vless://` / `trojan://` /
+# `ss://` share URI per *directly usable* proxy outbound, i.e. one that does
+# NOT declare `streamSettings.sockopt.dialerProxy` (a chained / multi-hop
+# upstream that cannot be expressed as a single share link). The resulting URIs
+# carry the standard query params the facade already understands
+# (security/sni/fp/pbk/sid/flow/type/path/host/mode/alpn), so they flow through
+# the existing sing_box_cf_add_proxy_outbound path unchanged. The outbound tag
+# (or the config `remarks`) becomes the URI fragment so the node keeps a
+# human-readable name.
+#
+# CRITICAL: OpenWRT's jq has no Oniguruma, so the program below uses only
+# explicit string operations (no test/match/sub/gsub). It also keeps every
+# query VALUE free of '& ? # %' and whitespace, because url_get_query_param()
+# (helpers.sh) stops a value at the first such delimiter.
+#
+# Arguments:
+#   src_file: path to the raw downloaded subscription body
+# Returns:
+#   0 and prints the URI lines to stdout when at least one outbound converted;
+#   1 (and prints nothing) otherwise.
+xray_json_to_uri_lines() {
+    local src_file="$1"
+
+    [ -s "$src_file" ] || return 1
+
+    # Quick structural gate before invoking jq: the body must be valid JSON
+    # whose (array element | object) carries Xray-style proxy outbounds. We let
+    # jq make the authoritative decision and emit the URIs in one pass.
+    jq -er '
+        # Normalize the document to an array of Xray config objects.
+        (if type == "array" then . else [.] end) as $configs
+
+        # A query value is only safe for url_get_query_param when it is present
+        # (not JSON null) and carries none of these delimiters/whitespace;
+        # otherwise drop the param entirely. NB: a missing Xray field reads as
+        # JSON null, and (null | tostring) == "null" — we must treat that as
+        # absent, never emit a literal "null" value (e.g. sid=null).
+        | def safe($v):
+            if $v == null then ""
+            else
+              ($v | tostring) as $s
+              | if ($s == "") then ""
+                elif ($s | (index("&") // index("?") // index("#")
+                            // index(" ") // index("%")
+                            // index("\t") // index("\n"))) != null then ""
+                else $s end
+            end;
+
+        # Build "key=value" only when value is present and delimiter-safe.
+        def kv($k; $v):
+            safe($v) as $s
+            | if $s == "" then empty else ($k + "=" + $s) end;
+
+        [ $configs[]
+          | (.remarks // "") as $cfg_name
+          | (.outbounds // [])[]
+          | select(type == "object")
+          | select(.protocol == "vless" or .protocol == "trojan"
+                   or .protocol == "shadowsocks")
+          # Skip chained / multi-hop outbounds: not representable as one URI.
+          | select((.streamSettings.sockopt.dialerProxy // "") == "")
+          | . as $ob
+          | (.streamSettings // {}) as $ss
+          | ($ss.network // "tcp") as $net
+          | ($ss.security // "") as $sec
+          | ($ss.realitySettings // {}) as $reality
+          | ($ss.tlsSettings // $ss.realitySettings // {}) as $tls
+          # vnext (vless/vmess) vs servers (trojan/shadowsocks) addressing.
+          | ($ob.settings.vnext[0] // $ob.settings.servers[0] // {}) as $peer
+          | ($peer.users[0] // {}) as $user
+          | ($peer.address // "") as $host
+          | ($peer.port // "") as $port
+          | select($host != "" and ($port | tostring) != "")
+          | ($ob.tag // $cfg_name) as $name
+          # Build the query param list per protocol, dropping empties.
+          | (
+              if $ob.protocol == "vless" then
+                ([ "encryption=none",
+                   ("type=" + $net),
+                   kv("flow"; $user.flow),
+                   (if $sec != "" then ("security=" + $sec) else empty end),
+                   kv("sni"; ($tls.serverName // "")) ])
+                + (if $sec == "reality" then
+                     [ kv("pbk"; $reality.publicKey),
+                       kv("sid"; $reality.shortId),
+                       kv("fp"; ($reality.fingerprint // "chrome")) ]
+                   else
+                     [ kv("fp"; ($tls.fingerprint // "")) ]
+                   end)
+              elif $ob.protocol == "trojan" then
+                [ ("type=" + $net),
+                  (if $sec != "" then ("security=" + ($sec)) else "security=tls" end),
+                  kv("sni"; ($tls.serverName // "")),
+                  kv("fp"; ($tls.fingerprint // "")) ]
+              else
+                [ ("type=" + $net) ]
+              end
+            ) as $base
+          # Transport-specific params (ws / xhttp / grpc).
+          | (
+              if $net == "ws" then
+                [ kv("path"; ($ss.wsSettings.path // "")),
+                  kv("host"; ($ss.wsSettings.headers.Host // "")) ]
+              elif $net == "xhttp" then
+                [ kv("path"; ($ss.xhttpSettings.path // "")),
+                  kv("host"; ($ss.xhttpSettings.host // "")),
+                  kv("mode"; ($ss.xhttpSettings.mode // "")) ]
+              elif $net == "grpc" then
+                [ kv("serviceName"; ($ss.grpcSettings.serviceName // "")) ]
+              else [] end
+            ) as $transport
+          # alpn is a JSON array in Xray; flatten to a comma string (no spaces).
+          | ([ ($tls.alpn // [])[] | tostring ] | join(",")) as $alpn_str
+          | ($base + $transport
+             + (if $alpn_str != "" then [ kv("alpn"; $alpn_str) ] else [] end)
+             | map(select(. != null and . != ""))) as $query
+          # Credential: uuid for vless, password for trojan/shadowsocks.
+          | (if $ob.protocol == "vless" then ($user.id // "")
+             else ($peer.password // $ob.settings.password // "") end) as $cred
+          | select($cred != "")
+          | ($ob.protocol
+             | if . == "shadowsocks" then "ss" else . end) as $scheme
+          # The connection part (no #fragment) is the dedup key: providers that
+          # ship one server set across many "profiles" repeat identical nodes
+          # with only the display name differing, which would otherwise inflate
+          # the list into thousands of duplicates.
+          | ($scheme + "://" + $cred + "@" + $host + ":" + ($port | tostring)
+             + (if ($query | length) > 0 then "?" + ($query | join("&")) else "" end)
+            ) as $conn
+          | { conn: $conn,
+              uri: ($conn + (if $name != "" then "#" + $name else "" end)) }
+        ]
+        # Deduplicate on $conn, preserving first-seen order (no sort): a
+        # label/break reduce over already-seen keys. Avoids unique_by (which
+        # reorders) and stays within the no-regex jq subset on OpenWRT.
+        | reduce .[] as $e ({ seen: [], out: [] };
+            if (.seen | index($e.conn)) != null then .
+            else .seen += [$e.conn] | .out += [$e.uri] end)
+        | .out
+        | select(length > 0)
+        | .[]
+    ' "$src_file" 2>/dev/null
+}
+
+# Count the Xray-JSON proxy outbounds that look like real nodes but use a
+# protocol the NetShift facade cannot build (today: vmess — the facade has no
+# vmess outbound). These are silently dropped by xray_json_to_uri_lines, so we
+# count them separately to surface an explicit warning to the user instead of
+# leaving them to wonder why a node count came up short. Chained (dialerProxy)
+# outbounds are NOT counted here — those are deliberately collapsed, not
+# "unsupported". Prints a single integer (0 when none / on any error).
+xray_json_count_unsupported() {
+    local src_file="$1"
+
+    [ -s "$src_file" ] || {
+        echo 0
+        return 0
+    }
+
+    jq -er '
+        [ (if type == "array" then . else [.] end)[]
+          | (.outbounds // [])[]
+          | select(type == "object")
+          | select((.streamSettings.sockopt.dialerProxy // "") == "")
+          | select(.protocol == "vmess")
+        ] | length
+    ' "$src_file" 2>/dev/null || echo 0
+}
+
 # Fallback subscription parser.
 #
 # Many providers do not return a sing-box JSON config. Instead they return
 # either (a) a base64-encoded list of proxy URIs, or (b) a plaintext list of
 # proxy URIs (one per line), possibly interspersed with '#comment' metadata
-# lines. This function decodes/parses such a body into a minimal sing-box
-# configuration ({"outbounds":[...]}) so the normal persist + merge path can
-# consume it unchanged.
+# lines, or (c) an "Xray JSON" config (object or array of objects, handled via
+# xray_json_to_uri_lines above). This function decodes/parses such a body into
+# a minimal sing-box configuration ({"outbounds":[...]}) so the normal persist
+# + merge path can consume it unchanged.
 #
 # It lives in helpers.sh (alongside validate_subscription_file). It calls
 # sing_box_cf_add_proxy_outbound, which is defined later in
@@ -1002,7 +1302,7 @@ normalize_subscription_to_singbox() {
     local raw stripped candidate pad_len decoded bom
     local udp_over_tcp config new_config lines_file
     local line scheme idx kept skipped before_count after_count final_count
-    local fragment display_name
+    local fragment display_name first_char xray_uris xray_unsupported
 
     [ -s "$src_file" ] || return 1
     # Strip a leading UTF-8 BOM (EF BB BF) if present; it would otherwise break
@@ -1013,6 +1313,32 @@ normalize_subscription_to_singbox() {
     [ -n "$raw" ] || raw="$(cat "$src_file" 2>/dev/null)"
     [ -n "$raw" ] || return 1
 
+    # Xray-JSON detection (before base64/URI handling). When the body is a JSON
+    # object/array of Xray client configs, convert its proxy outbounds to share
+    # URIs and feed those through the URI loop below. Only attempt this when the
+    # first non-whitespace byte is '{' or '[' (cheap pre-gate) so plaintext URI
+    # lists never pay the jq cost.
+    first_char="$(printf '%s' "$raw" | sed -n '1{s/^[[:space:]]*//;s/\(.\).*/\1/p;};1q' 2>/dev/null)"
+    case "$first_char" in
+    '{' | '[')
+        xray_uris="$(xray_json_to_uri_lines "$src_file" 2>/dev/null)"
+        if [ -n "$xray_uris" ]; then
+            log "Detected Xray JSON subscription for '$section'; converting proxy outbounds to share URIs" "debug"
+            raw="$xray_uris"
+            # Surface unsupported protocols (vmess) explicitly: they are dropped
+            # by the converter because the facade cannot build them, and a silent
+            # drop looks like a bug to the user.
+            xray_unsupported="$(xray_json_count_unsupported "$src_file")"
+            case "$xray_unsupported" in
+            '' | *[!0-9]*) xray_unsupported=0 ;;
+            esac
+            if [ "$xray_unsupported" -gt 0 ]; then
+                log "Xray JSON subscription for '$section' has $xray_unsupported VMess node(s); VMess is not supported and they were skipped" "warn"
+            fi
+        fi
+        ;;
+    esac
+
     # Decide whether the body is a base64 blob or already plaintext URIs.
     # Be conservative: only treat as base64 when the raw body has NO '://'
     # substring (a plaintext URI list always contains '://') but the decoded

netshift/files/usr/lib/nft.sh

@@ -14,6 +14,13 @@ nft_create_ipv4_set() {
     nft add set inet "$table" "$name" '{ type ipv4_addr; flags interval; auto-merge; }'
 }
 
+nft_create_ipv6_set() {
+    local table="$1"
+    local name="$2"
+
+    nft add set inet "$table" "$name" '{ type ipv6_addr; flags interval; auto-merge; }'
+}
+
 nft_create_ifname_set() {
     local table="$1"
     local name="$2"
@@ -68,4 +75,4 @@ nft_add_set_elements_from_file_chunked() {
         log "Adding $count elements to nft set $nft_set_name" "debug"
         nft_add_set_elements "$nft_table_name" "$nft_set_name" "$array"
     fi
-}
+}

netshift/files/usr/lib/sing_box_config_facade.sh

@@ -62,6 +62,12 @@ sing_box_cf_add_proxy_outbound() {
     local url="$3"
     local udp_over_tcp="$4"
 
+    # Keep the RAW (pre-url_decode) link for schemes that base64-decode the
+    # WHOLE payload (vmess). url_decode rewrites '+'->space, which corrupts
+    # standard base64 bodies (the '+' is in the base64 alphabet). See the
+    # vmess) case below.
+    local raw_url="$3"
+
     url=$(url_decode "$url")
     url=$(url_strip_fragment "$url")
 
@@ -163,6 +169,57 @@ sing_box_cf_add_proxy_outbound() {
             "$obfuscator_password" "$upload_mbps" "$download_mbps")
         config=$(_add_outbound_security "$config" "$tag" "$url")
         ;;
+    vmess)
+        # ─── REFERENCE EXTENDED-GATING PATTERN (Tier-1 protocols copy this) ───
+        # Generation is gated behind sing-box-extended. On a stock sing-box build
+        # we log a clear message and return the config UNCHANGED (no exit 1, no
+        # outbound added) so generation degrades safely and keeps the last-good
+        # config. tuic/hysteria1/anytls/shadowtls reuse this exact block.
+        if ! is_sing_box_extended; then
+            log "VMess requires sing-box-extended. Install sing-box-extended and retry." "error"
+            echo "$config"
+            return 0
+        fi
+        # ─────────────────────────────────────────────────────────────────────
+
+        local tag vmess_json vm_server vm_port vm_uuid vm_security vm_alter_id
+        local vm_net vm_host vm_path vm_tls vm_sni vm_alpn vm_fp
+
+        tag=$(get_outbound_tag_by_section "$section")
+
+        # Primary format: vmess://base64(JSON) (V2RayN). The URL form
+        # (vmess://<uuid>@<host>:<port>?...) is a phase-2 follow-on; not handled here.
+        #
+        # CRITICAL: VMess base64-decodes the WHOLE payload, so it MUST use the
+        # RAW pre-url_decode link ($raw_url, NOT $url). url_decode rewrites
+        # '+'->space, which would corrupt standard base64 bodies containing '+'.
+        # Future Tier-1 copiers (tuic/etc.) that base64-decode a whole payload
+        # MUST also use $raw_url for the same reason.
+        vmess_json=$(vmess_link_to_json "$raw_url")
+        if [ -z "$vmess_json" ] || ! echo "$vmess_json" | jq -e 'type == "object"' > /dev/null 2>&1; then
+            log "Cannot decode VMess link or it does not match the expected base64(JSON) format. Aborted." "fatal"
+            exit 1
+        fi
+
+        # Numbers-as-strings are tolerated: extract every field as a string.
+        vm_server=$(echo "$vmess_json" | jq -r '.add // ""')
+        vm_port=$(echo "$vmess_json" | jq -r '.port // "" | tostring')
+        vm_uuid=$(echo "$vmess_json" | jq -r '.id // ""')
+        vm_security=$(echo "$vmess_json" | jq -r '.scy // "" | tostring')
+        vm_alter_id=$(echo "$vmess_json" | jq -r '.aid // "" | tostring')
+        vm_net=$(echo "$vmess_json" | jq -r '.net // "" | tostring')
+        vm_host=$(echo "$vmess_json" | jq -r '.host // "" | tostring')
+        vm_path=$(echo "$vmess_json" | jq -r '.path // "" | tostring')
+        vm_tls=$(echo "$vmess_json" | jq -r '.tls // "" | tostring')
+        vm_sni=$(echo "$vmess_json" | jq -r '.sni // "" | tostring')
+        vm_alpn=$(echo "$vmess_json" | jq -r '.alpn // "" | tostring')
+        vm_fp=$(echo "$vmess_json" | jq -r '.fp // "" | tostring')
+
+        config=$(sing_box_cm_add_vmess_outbound "$config" "$tag" "$vm_server" "$vm_port" "$vm_uuid" \
+            "$vm_security" "$vm_alter_id")
+        config=$(_add_vmess_transport_and_security "$config" "$tag" "$vm_net" "$vm_host" "$vm_path" \
+            "$vm_tls" "$vm_sni" "$vm_alpn" "$vm_fp" "$vm_server")
+        ;;
     *)
         log "Unsupported proxy $scheme type. Aborted." "fatal"
         exit 1
@@ -290,6 +347,89 @@ _add_outbound_transport() {
     echo "$config"
 }
 
+#######################################
+# Apply VMess TLS + transport to an already-added vmess outbound.
+# VMess (V2RayN base64-JSON) carries transport in the JSON `net` field and TLS
+# in `tls`/`sni`/`alpn`/`fp` — NOT in URL query params. So we do NOT route
+# through _add_outbound_security / _add_outbound_transport (which read
+# url_get_query_param); we set everything from the decoded-JSON values here.
+# Arguments:
+#   config: string (JSON), sing-box configuration to modify
+#   tag: string, outbound tag to mutate
+#   net: string, vmess `net` (ws|grpc|h2|tcp|"")
+#   host: string, vmess `host`
+#   path: string, vmess `path`
+#   tls: string, vmess `tls` ("tls"/"1"/"true" enables TLS)
+#   sni: string, vmess `sni`
+#   alpn: string, vmess `alpn` (comma-separated)
+#   fp: string, vmess `fp` (uTLS fingerprint)
+#   server: string, vmess `add` (TLS server_name fallback when sni is empty)
+# Outputs:
+#   Writes updated JSON configuration to stdout
+#######################################
+_add_vmess_transport_and_security() {
+    local config="$1"
+    local outbound_tag="$2"
+    local net="$3"
+    local host="$4"
+    local path="$5"
+    local tls="$6"
+    local sni="$7"
+    local alpn="$8"
+    local fp="$9"
+    local server="${10}"
+
+    # Transport from `net` (NOT a query `type`).
+    local tls_required=0
+    case "$net" in
+    ws)
+        config=$(sing_box_cm_set_ws_transport_for_outbound "$config" "$outbound_tag" "$path" "$host")
+        ;;
+    grpc)
+        # The core derives the gRPC serviceName from `path` (falls back to `host`).
+        local grpc_service_name="$path"
+        [ -n "$grpc_service_name" ] || grpc_service_name="$host"
+        config=$(sing_box_cm_set_grpc_transport_for_outbound "$config" "$outbound_tag" "$grpc_service_name")
+        ;;
+    h2)
+        # HTTP/2 transport mandates TLS.
+        config=$(sing_box_cm_set_http_transport_for_outbound "$config" "$outbound_tag" "$path" "$host")
+        tls_required=1
+        ;;
+    tcp | "") ;;
+    *)
+        log "Unknown VMess transport '$net' detected." "error"
+        ;;
+    esac
+
+    # TLS from `tls` (or forced by h2 transport).
+    local tls_enabled=0
+    case "$tls" in
+    tls | 1 | true) tls_enabled=1 ;;
+    esac
+    [ "$tls_required" -eq 1 ] && tls_enabled=1
+
+    if [ "$tls_enabled" -eq 1 ]; then
+        local server_name alpn_json
+        server_name="$sni"
+        [ -n "$server_name" ] || server_name="$server"
+        alpn_json=$(comma_string_to_json_array "$alpn")
+        config=$(
+            sing_box_cm_set_tls_for_outbound \
+                "$config" \
+                "$outbound_tag" \
+                "$server_name" \
+                "" \
+                "$([ "$alpn_json" = "[]" ] && echo null || echo "$alpn_json")" \
+                "$fp" \
+                "" \
+                ""
+        )
+    fi
+
+    echo "$config"
+}
+
 sing_box_cf_add_json_outbound() {
     local config="$1"
     local section="$2"
@@ -365,6 +505,10 @@ sing_box_cf_add_single_key_reject_rule() {
 # Arguments:
 #   config: string (JSON), sing-box configuration the batch will be merged into
 #   subscription_json_path: string, path to the downloaded subscription JSON file
+#   include_keywords_json: string (JSON array), keep only nodes whose display name
+#       contains at least one of these (OR). Empty array ([]) = keep all.
+#   exclude_keywords_json: string (JSON array), drop any node whose display name
+#       contains at least one of these (OR). Empty array ([]) = no exclusion.
 # Outputs:
 #   Writes a JSON object to stdout:
 #     { outbounds: [ {type,...,tag} ... ], tags: [..], names: [..],
@@ -373,8 +517,13 @@ sing_box_cf_add_single_key_reject_rule() {
 sing_box_cf_prepare_subscription_batch() {
     local config="$1"
     local subscription_json_path="$2"
+    local include_keywords_json="${3:-[]}"
+    local exclude_keywords_json="${4:-[]}"
     local sing_box_extended="false"
 
+    [ -n "$include_keywords_json" ] || include_keywords_json="[]"
+    [ -n "$exclude_keywords_json" ] || exclude_keywords_json="[]"
+
     if is_sing_box_extended; then
         sing_box_extended="true"
     fi
@@ -383,7 +532,35 @@ sing_box_cf_prepare_subscription_batch() {
     # the subscription JSON is slurped from its file path.
     printf '%s' "$config" | jq -c \
         --slurpfile sub "$subscription_json_path" \
-        --argjson extended "$sing_box_extended" '
+        --argjson extended "$sing_box_extended" \
+        --argjson include_keywords "$include_keywords_json" \
+        --argjson exclude_keywords "$exclude_keywords_json" '
+        # Codepoint-based case fold. OpenWrt jq has no Oniguruma and ascii_downcase
+        # only maps ASCII A-Z (leaving Cyrillic mixed-case), so define an inline
+        # fold (this jq program does NOT import helpers.jq). It lowercases ASCII
+        # AND Cyrillic (incl. the Yo letter outside the contiguous block); emoji
+        # and all other scripts pass through unchanged and thus match as exact
+        # codepoint substrings.
+        def ucfold:
+          explode
+          | map(
+              if   (. >= 65   and . <= 90)   then . + 32     # ASCII A-Z -> a-z
+              elif (. >= 1040 and . <= 1071) then . + 32     # Cyrillic А-Я -> а-я
+              elif (. == 1025)               then 1105       # Ё -> ё
+              else . end)
+          | implode;
+        # Normalise the keyword lists: drop empty items and precompute the
+        # case-folded form once. ucfold folds ASCII and Cyrillic; emoji/other
+        # scripts are matched as exact codepoint substrings.
+        # NB: "include"/"exclude" are reserved jq keywords, hence $inc/$exc.
+        ([$include_keywords[]? | tostring | select(length > 0) | ucfold]) as $inc
+        | ([$exclude_keywords[]? | tostring | select(length > 0) | ucfold]) as $exc
+        # A node "matches" a normalised keyword list when its case-folded name
+        # contains any of the keywords (substring via index, NO regex/Oniguruma).
+        # Bind each keyword to $kw so index() receives the keyword, not the name.
+        | def name_passes_keywords($lc):
+            (($inc | length) == 0 or any($inc[]; . as $kw | ($lc | index($kw)) != null))
+            and (($exc | length) == 0 or all($exc[]; . as $kw | ($lc | index($kw)) == null));
         # Reserved tags already used by the working config (stdin is the config).
         ([.outbounds[]?.tag // empty]) as $existing
         # Candidate proxy outbounds from the subscription (preserve order).
@@ -393,7 +570,16 @@ sing_box_cf_prepare_subscription_batch() {
             .type != "direct" and
             .type != "dns" and
             .type != "block"
-          )] as $candidates
+          )] as $all_candidates
+        # Keyword whitelist/blacklist filter on the display name. Runs BEFORE the
+        # static-unsupported filter and tag dedup, so dropped nodes never get
+        # tags and never reach sing-box check. Covers native + fallback-parsed
+        # subscriptions (both consume this batch).
+        | [$all_candidates[]
+            | . as $ob
+            | (($ob.remark // $ob.tag // "") | tostring) as $name
+            | select(name_passes_keywords($name | ucfold))
+          ] as $candidates
         | ($candidates | length) as $total
         # Statically reject outbounds the current sing-box build cannot load.
         | [ $candidates[]
@@ -548,6 +734,10 @@ sing_box_cf_apply_subscription_range() {
 #   config: string (JSON), sing-box configuration to modify
 #   section: string, the UCI section name
 #   subscription_json_path: string, path to the downloaded subscription JSON file
+#   include_keywords_json: string (JSON array, optional), keyword whitelist (OR);
+#       empty/[] keeps all nodes. Forwarded to the prepare batch.
+#   exclude_keywords_json: string (JSON array, optional), keyword blacklist (OR);
+#       empty/[] excludes nothing. Forwarded to the prepare batch.
 # Outputs:
 #   Writes updated JSON configuration to stdout
 #   Sets global variable SUBSCRIPTION_OUTBOUND_TAGS (comma-separated list of tags)
@@ -558,6 +748,11 @@ sing_box_cf_add_subscription_outbounds() {
     local config="$1"
     local section="$2"
     local subscription_json_path="$3"
+    local include_keywords_json="${4:-[]}"
+    local exclude_keywords_json="${5:-[]}"
+
+    [ -n "$include_keywords_json" ] || include_keywords_json="[]"
+    [ -n "$exclude_keywords_json" ] || exclude_keywords_json="[]"
 
     SUBSCRIPTION_OUTBOUND_TAGS=""
     SUBSCRIPTION_OUTBOUND_TAGS_JSON="[]"
@@ -570,9 +765,17 @@ sing_box_cf_add_subscription_outbounds() {
         return 1
     fi
 
-    # Build the entire batch (filter + dedup tags) in one jq pass.
+    # Whether keyword filtering is active (for distinct empty-result logging).
+    local keyword_filter_active=0
+    if [ "$include_keywords_json" != "[]" ] || [ "$exclude_keywords_json" != "[]" ]; then
+        keyword_filter_active=1
+    fi
+
+    # Build the entire batch (keyword filter + static filter + dedup tags) in one
+    # jq pass.
     local prepared
-    prepared=$(sing_box_cf_prepare_subscription_batch "$config" "$subscription_json_path")
+    prepared=$(sing_box_cf_prepare_subscription_batch "$config" "$subscription_json_path" \
+        "$include_keywords_json" "$exclude_keywords_json")
     if [ -z "$prepared" ]; then
         log "Failed to parse subscription outbounds JSON" "error"
         echo "$config"
@@ -584,7 +787,23 @@ sing_box_cf_add_subscription_outbounds() {
     kept_count=$(printf '%s' "$prepared" | jq -r '.count // 0' 2>/dev/null)
     statically_skipped=$(printf '%s' "$prepared" | jq -r '.skipped // 0' 2>/dev/null)
 
+    if [ "$keyword_filter_active" -eq 1 ]; then
+        # candidate_total here is the post-keyword-filter candidate count; report
+        # kept vs. filtered_out so an over-strict filter is diagnosable.
+        local raw_candidate_total filtered_out
+        raw_candidate_total=$(printf '%s' "$config" | jq -c \
+            --slurpfile sub "$subscription_json_path" \
+            '[$sub[0].outbounds[]? | select(.type != "selector" and .type != "urltest" and .type != "direct" and .type != "dns" and .type != "block")] | length' 2>/dev/null)
+        [ -n "$raw_candidate_total" ] || raw_candidate_total=0
+        filtered_out=$((raw_candidate_total - candidate_total))
+        [ "$filtered_out" -ge 0 ] || filtered_out=0
+        log "Subscription keyword filter for section '$section': kept=$candidate_total, filtered_out=$filtered_out" "info"
+    fi
+
     if [ -z "$candidate_total" ] || [ "$candidate_total" -eq 0 ]; then
+        if [ "$keyword_filter_active" -eq 1 ]; then
+            log "Subscription keyword filter for section '$section' removed all nodes; using a temporary blocked outbound" "warn"
+        fi
         log "No proxy outbounds found in subscription JSON" "error"
         echo "$config"
         return 1

netshift/files/usr/lib/sing_box_config_manager.sh

@@ -223,15 +223,20 @@ sing_box_cm_add_fakeip_dns_server() {
     local config="$1"
     local tag="$2"
     local inet4_range="$3"
+    local inet6_range="$4"
 
     echo "$config" | jq \
         --arg tag "$tag" \
         --arg inet4_range "$inet4_range" \
-        '.dns.servers += [{
-			type: "fakeip",
-			tag: $tag,
-			inet4_range: $inet4_range,
-		}]'
+        --arg inet6_range "$inet6_range" \
+        '.dns.servers += [(
+            {
+                type: "fakeip",
+                tag: $tag,
+                inet4_range: $inet4_range
+            }
+            + (if $inet6_range != "" then { inet6_range: $inet6_range } else {} end)
+        )]'
 }
 
 #######################################
@@ -622,6 +627,56 @@ sing_box_cm_add_vless_outbound() {
         )]'
 }
 
+#######################################
+# Add a VMess outbound to the outbounds section of a sing-box JSON configuration.
+# Requires sing-box-extended on the router (gated by the facade).
+# Arguments:
+#   config: string (JSON), sing-box configuration to modify
+#   tag: string, identifier for the outbound
+#   server_address: string, IP address or hostname of the VMess server
+#   server_port: integer, port of the VMess server
+#   uuid: string, user UUID
+#   security: string, encryption method (optional; defaults to "auto" when empty)
+#   alter_id: integer, alterId (optional; omitted when empty or 0)
+# Outputs:
+#   Writes updated JSON configuration to stdout
+# Example:
+#   CONFIG=$(
+#       sing_box_cm_add_vmess_outbound "$CONFIG" "vmess-out" "example.com" 443 \
+#       "bf000d23-0752-40b4-affe-68f7707a9661" "auto" "0"
+#   )
+#######################################
+sing_box_cm_add_vmess_outbound() {
+    local config="$1"
+    local tag="$2"
+    local server_address="$3"
+    local server_port="$4"
+    local uuid="$5"
+    local security="$6"
+    local alter_id="$7"
+
+    [ -n "$security" ] || security="auto"
+
+    echo "$config" | jq \
+        --arg tag "$tag" \
+        --arg server_address "$server_address" \
+        --arg server_port "$server_port" \
+        --arg uuid "$uuid" \
+        --arg security "$security" \
+        --arg alter_id "$alter_id" \
+        '.outbounds += [(
+            {
+              type: "vmess",
+              tag: $tag,
+              server: $server_address,
+              server_port: ($server_port | tonumber),
+              uuid: $uuid,
+              security: $security
+            }
+            + (if $alter_id != "" and $alter_id != "0" then {alter_id: ($alter_id | tonumber)} else {} end)
+        )]'
+}
+
 #######################################
 # Add a Trojan outbound to the outbounds section of a sing-box JSON configuration.
 # Arguments:
@@ -834,6 +889,45 @@ sing_box_cm_set_ws_transport_for_outbound() {
         )'
 }
 
+#######################################
+# Set HTTP/2 transport settings for an outbound in a sing-box JSON configuration.
+# Used for VMess net=h2 links (sing-box "http" transport). HTTP/2 transport
+# mandates TLS, so the caller must also set TLS on the outbound.
+# Arguments:
+#   config: string (JSON), sing-box configuration to modify
+#   tag: string, identifier of the outbound to modify
+#   path: string, HTTP path (optional)
+#   host: string, Host header (single host; optional)
+# Outputs:
+#   Writes updated JSON configuration to stdout
+# Example:
+#   CONFIG=$(sing_box_cm_set_http_transport_for_outbound "$CONFIG" "vmess-out" "/path" "example.com")
+#######################################
+sing_box_cm_set_http_transport_for_outbound() {
+    local config="$1"
+    local tag="$2"
+    local path="$3"
+    local host="$4"
+
+    echo "$config" | jq \
+        --arg tag "$tag" \
+        --arg path "$path" \
+        --arg host "$host" \
+        '.outbounds |= map(
+            if .tag == $tag then
+                . + {
+                    transport: (
+                        { type: "http" }
+                        + (if $path != "" then {path: $path} else {} end)
+                        + (if $host != "" then {host: [$host]} else {} end)
+                    )
+                }
+            else
+                .
+            end
+        )'
+}
+
 #######################################
 # Set XHTTP transport settings for an outbound in a sing-box JSON configuration.
 # Requires sing-box-extended on the router.
@@ -1264,6 +1358,51 @@ sing_box_cm_add_reject_route_rule() {
         }]'
 }
 
+#######################################
+# Add a DoH blocking reject route rule with an inline ruleset containing known
+# public DoH server IP ranges.
+# Arguments:
+#   config: string (JSON), sing-box configuration to modify
+#   tag: string, identifier for the route rule and ruleset
+#   inbound: string, inbound tag to match
+#   doh_ipv4_cidrs: string, space-separated IPv4 CIDRs to block
+#   doh_ipv6_cidrs: string, space-separated IPv6 CIDRs to block
+# Outputs:
+#   Writes updated JSON configuration to stdout
+#######################################
+sing_box_cm_add_doh_block_route_rule() {
+    local config="$1"
+    local tag="$2"
+    local inbound="$3"
+    local doh_ipv4_cidrs="$4"
+    local doh_ipv6_cidrs="${5:-}"
+
+    local ruleset_tag cidrs_json
+    ruleset_tag="${tag}-ruleset"
+    cidrs_json=$(printf '%s %s' "$doh_ipv4_cidrs" "$doh_ipv6_cidrs" | jq -R 'split(" ") | map(select(. != ""))')
+
+    config=$(echo "$config" | jq \
+        --arg tag "$ruleset_tag" \
+        --argjson ip_cidr "$cidrs_json" \
+        '.route.rule_set += [{
+            type: "inline",
+            tag: $tag,
+            rules: [{ ip_cidr: $ip_cidr }]
+        }]')
+
+    echo "$config" | jq \
+        --arg service_tag "$SERVICE_TAG" \
+        --arg tag "$tag" \
+        --arg inbound "$inbound" \
+        --arg ruleset_tag "$ruleset_tag" \
+        '.route.rules += [{
+            action: "reject",
+            inbound: $inbound,
+            rule_set: $ruleset_tag,
+            $service_tag: $tag
+        }]'
+}
+
 #######################################
 # Add a hijack-dns rule to the route section of a sing-box JSON configuration.
 # Arguments:

opencode.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "AGENTS.md",
+    "docs/agent-rules/project-core.md",
+    "docs/agent-rules/backend-shell.md",
+    "docs/agent-rules/frontend-luci.md",
+    "docs/agent-rules/packaging.md"
+  ]
+}

tests/docker-compose.yml

@@ -8,8 +8,10 @@
 # Run specific test:
 #   docker compose -f tests/docker-compose.yml run --rm netshift-test <test-name>
 #
-# Test names: all, deps, syntax, config, helpers, nft,
-#             dnsmasq, lifecycle, diagnostics, subscription
+# Test names: all, deps, syntax, config, helpers, jq, cm, sb, nft,
+#             nftv6, diagnostics, subscription, insecure, rejected,
+#             jobstate, selfheal, dnsdetour, globalproxy, stablecheck,
+#             extcheck, selfupdate
 # ──────────────────────────────────────────────────────────────────
 
 services: