diff --git a/web/docs/lint.md b/web/docs/lint.md
new file mode 100644
index 0000000000..051f9e6ecd
--- /dev/null
+++ b/web/docs/lint.md
@@ -0,0 +1,51 @@
+# Lint Guide
+
+We use ESLint and Typescript to maintain code quality and consistency across the project.
+
+## ESLint
+
+### Common Flags
+
+**File/folder targeting**: Append paths to lint specific files or directories.
+
+```sh
+pnpm eslint [options] file.js [file.js] [dir]
+```
+
+**`--cache`**: Caches lint results for faster subsequent runs. Keep this enabled by default; only disable when you encounter unexpected lint results.
+
+**`--concurrency`**: Enables multi-threaded linting. Use `--concurrency=auto` or experiment with specific numbers to find the optimal setting for your machine. Keep this enabled when linting multiple files.
+
+- [ESLint multi-thread linting blog post](https://eslint.org/blog/2025/08/multithread-linting/)
+
+**`--fix`**: Automatically fixes auto-fixable rule violations. Always review the diff before committing to ensure no unintended changes.
+
+**`--quiet`**: Suppresses warnings and only shows errors. Useful when you want to reduce noise from existing issues.
+
+**`--suppress-all`**: Temporarily suppresses error-level violations and records them, allowing CI to pass. Treat this as an escape hatch—fix these errors when time permits.
+
+**`--prune-suppressions`**: Removes outdated suppressions after you've fixed the underlying errors.
+
+- [ESLint bulk suppressions blog post](https://eslint.org/blog/2025/04/introducing-bulk-suppressions/)
+
+### Type-Aware Linting
+
+Some ESLint rules require type information, such as [no-leaked-conditional-rendering](https://www.eslint-react.xyz/docs/rules/no-leaked-conditional-rendering). However, [typed linting via typescript-eslint](https://typescript-eslint.io/getting-started/typed-linting) is too slow for practical use, so we use [TSSLint](https://github.com/johnsoncodehk/tsslint) instead.
+
+```sh
+pnpm lint:tss
+```
+
+This command lints the entire project and is intended for final verification before committing or pushing changes.
+
+## Type Check
+
+You should be able to see suggestions from TypeScript in your editor for all open files.
+
+However, it can be useful to run the TypeScript 7 command-line (tsgo) to type check all files:
+
+```sh
+pnpm type-check:tsgo
+```
+
+Prefer using `tsgo` for type checking as it is significantly faster than the standard TypeScript compiler. Only fall back to `pnpm type-check` (which uses `tsc`) if you encounter unexpected results.
diff --git a/web/testing/testing.md b/web/docs/test.md
similarity index 99%
rename from web/testing/testing.md
rename to web/docs/test.md
index 47341e445e..cac0e0e351 100644
--- a/web/testing/testing.md
+++ b/web/docs/test.md
@@ -360,11 +360,11 @@ describe('ComponentName', () => {
let mockPortalOpenState = false
vi.mock('@/app/components/base/portal-to-follow-elem', () => ({
- PortalToFollowElem: ({ children, open, ...props }: any) => {
+ PortalToFollowElem: ({ children, open, ...props }) => {
mockPortalOpenState = open || false // Update shared state
return
{children}
},
- PortalToFollowElemContent: ({ children }: any) => {
+ PortalToFollowElemContent: ({ children }) => {
// ✅ Matches actual: returns null when open is false
if (!mockPortalOpenState)
return null
diff --git a/web/eslint-suppressions.json b/web/eslint-suppressions.json
index 965ac492fb..2662e979c1 100644
--- a/web/eslint-suppressions.json
+++ b/web/eslint-suppressions.json
@@ -4371,11 +4371,6 @@
"count": 10
}
},
- "testing/testing.md": {
- "ts/no-explicit-any": {
- "count": 2
- }
- },
"types/app.ts": {
"ts/no-explicit-any": {
"count": 1
diff --git a/web/scripts/analyze-component.js b/web/scripts/analyze-component.js
index b09301503c..2fdff2f3d0 100755
--- a/web/scripts/analyze-component.js
+++ b/web/scripts/analyze-component.js
@@ -337,7 +337,7 @@ Test file under review:
${testPath}
Checklist (ensure every item is addressed in your review):
-- Confirm the tests satisfy all requirements listed above and in web/testing/TESTING.md.
+- Confirm the tests satisfy all requirements listed above and in web/docs/test.md.
- Verify Arrange → Act → Assert structure, mocks, and cleanup follow project conventions.
- Ensure all detected component features (state, effects, routing, API, events, etc.) are exercised, including edge cases and error paths.
- Check coverage of prop variations, null/undefined inputs, and high-priority workflows implied by usage score.
@@ -382,7 +382,7 @@ Examples:
# Review existing test
pnpm analyze-component app/components/base/button/index.tsx --review
-For complete testing guidelines, see: web/testing/testing.md
+For complete testing guidelines, see: web/docs/test.md
`)
}