docs: federate scattered markdown files into centralized docs (#36756)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

docs/developer_portal/contributing/development-setup.md

@@ -653,7 +653,7 @@ export enum FeatureFlag {
 those specified under FEATURE_FLAGS in `superset_config.py`. For example, `DEFAULT_FEATURE_FLAGS = { 'FOO': True, 'BAR': False }` in `superset/config.py` and `FEATURE_FLAGS = { 'BAR': True, 'BAZ': True }` in `superset_config.py` will result
 in combined feature flags of `{ 'FOO': True, 'BAR': True, 'BAZ': True }`.
 
-The current status of the usability of each flag (stable vs testing, etc) can be found in `RESOURCES/FEATURE_FLAGS.md`.
+The current status of the usability of each flag (stable vs testing, etc) can be found in the [Feature Flags](/docs/configuration/feature-flags) documentation.
 
 ## Git Hooks
 

docs/developer_portal/contributing/howtos.md

@@ -342,26 +342,79 @@ ruff check --fix .
 
 Pre-commit hooks run automatically on `git commit` if installed.
 
-### TypeScript
+### TypeScript / JavaScript
 
-We use ESLint and Prettier for TypeScript:
+We use a hybrid linting approach combining OXC (Oxidation Compiler) for standard rules and a custom AST-based checker for Superset-specific patterns.
+
+#### Quick Commands
 
 ```bash
 cd superset-frontend
 
-# Run eslint checks
+# Run both OXC and custom rules
+npm run lint:full
+
+# Run OXC linter only (faster for most checks)
 npm run lint
 
+# Fix auto-fixable issues with OXC
+npm run lint-fix
+
+# Run custom rules checker only
+npm run check:custom-rules
+
 # Run tsc (typescript) checks
 npm run type
 
-# Fix lint issues
-npm run lint-fix
-
 # Format with Prettier
 npm run prettier
 ```
 
+#### Architecture
+
+The linting system consists of two components:
+
+1. **OXC Linter** (`oxlint`) - A Rust-based linter that's 50-100x faster than ESLint
+   - Handles all standard JavaScript/TypeScript rules
+   - Configured via `oxlint.json`
+   - Runs via `npm run lint` or `npm run lint-fix`
+
+2. **Custom Rules Checker** - A Node.js AST-based checker for Superset-specific patterns
+   - Enforces no literal colors (use theme colors)
+   - Prevents FontAwesome usage (use @superset-ui/core Icons)
+   - Validates i18n template usage (no template variables)
+   - Runs via `npm run check:custom-rules`
+
+#### Why This Approach?
+
+- **50-100x faster linting** compared to ESLint for standard rules via OXC
+- **Apache-compatible** - No custom binaries, ASF-friendly
+- **Maintainable** - Custom rules in JavaScript, not Rust
+- **Flexible** - Can evolve as OXC adds plugin support
+
+#### Troubleshooting
+
+**"Plugin 'basic-custom-plugin' not found" Error**
+
+Ensure you're using the explicit config:
+```bash
+npx oxlint --config oxlint.json
+```
+
+**Custom Rules Not Running**
+
+Verify the AST parsing dependencies are installed:
+```bash
+npm ls @babel/parser @babel/traverse glob
+```
+
+#### Adding New Custom Rules
+
+1. Edit `scripts/check-custom-rules.js`
+2. Add a new check function following the AST visitor pattern
+3. Call the function in `processFile()`
+4. Test with `npm run check:custom-rules`
+
 ## GitHub Ephemeral Environments
 
 For every PR, an ephemeral environment is automatically deployed for testing.

docs/developer_portal/guidelines/frontend-style-guidelines.md

@@ -43,8 +43,9 @@ This is a list of statements that describe how we do frontend development in Sup
 - We organize our repo so similar files live near each other, and tests are co-located with the files they test.
   - See: [SIP-61](https://github.com/apache/superset/issues/12098)
 - We prefer small, easily testable files and components.
-- We use ESLint and Prettier to automatically fix lint errors and format the code.
+- We use OXC (oxlint) and Prettier to automatically fix lint errors and format the code.
   - We do not debate code formatting style in PRs, instead relying on automated tooling to enforce it.
   - If there's not a linting rule, we don't have a rule!
+  - See: [Linting How-Tos](../contributing/howtos#typescript--javascript)
 - We use [React Storybook](https://storybook.js.org/) and [Applitools](https://applitools.com/) to help preview/test and stabilize our components
   - A public Storybook with components from the `master` branch is available [here](https://apache-superset.github.io/superset-ui/?path=/story/*)

docs/developer_portal/index.md

@@ -86,7 +86,6 @@ Everything you need to contribute to the Apache Superset project. This section i
 - **[Configuration Guide](https://superset.apache.org/docs/configuration/configuring-superset)** - Setup and configuration
 
 ### Important Files
-- **[CONTRIBUTING.md](https://github.com/apache/superset/blob/master/CONTRIBUTING.md)** - Contribution guidelines
 - **[CLAUDE.md](https://github.com/apache/superset/blob/master/CLAUDE.md)** - LLM development guide
 - **[UPDATING.md](https://github.com/apache/superset/blob/master/UPDATING.md)** - Breaking changes log
 

docs/developer_portal/testing/e2e-testing.md

@@ -24,57 +24,204 @@ under the License.
 
 # End-to-End Testing
 
-🚧 **Coming Soon** 🚧
+Apache Superset uses Playwright for end-to-end testing, migrating from the legacy Cypress tests.
 
-Guide for writing and running end-to-end tests using Playwright and Cypress.
-
-## Topics to be covered:
+## Running Tests
 
 ### Playwright (Recommended)
-- Setting up Playwright environment
-- Writing reliable E2E tests
-- Page Object Model pattern
-- Handling async operations
-- Cross-browser testing
-- Visual regression testing
-- Debugging with Playwright Inspector
-- CI/CD integration
 
-### Cypress (Deprecated)
-- Legacy Cypress test maintenance
-- Migration to Playwright
-- Running existing Cypress tests
-
-## Quick Commands
-
-### Playwright
 ```bash
-# Run all Playwright tests
-npm run playwright:test
+cd superset-frontend
 
-# Run in headed mode (see browser)
-npm run playwright:headed
+# Run all tests
+npm run playwright:test
+# or: npx playwright test
 
 # Run specific test file
 npx playwright test tests/auth/login.spec.ts
 
-# Debug specific test
-npm run playwright:debug tests/auth/login.spec.ts
-
-# Open Playwright UI
+# Run with UI mode for debugging
 npm run playwright:ui
+# or: npx playwright test --ui
+
+# Run in headed mode (see browser)
+npm run playwright:headed
+# or: npx playwright test --headed
+
+# Debug specific test file
+npm run playwright:debug tests/auth/login.spec.ts
+# or: npx playwright test --debug tests/auth/login.spec.ts
 ```
 
 ### Cypress (Deprecated)
-```bash
-# Run Cypress tests
-cd superset-frontend/cypress-base
-npm run cypress-run-chrome
 
-# Open Cypress UI
-npm run cypress-debug
+Cypress tests are being migrated to Playwright. For legacy tests:
+
+```bash
+cd superset-frontend/cypress-base
+npm run cypress-run-chrome    # Headless
+npm run cypress-debug         # Interactive UI
 ```
 
----
+## Project Architecture
 
-*This documentation is under active development. Check back soon for updates!*
+```
+superset-frontend/playwright/
+├── components/core/     # Reusable UI components
+├── pages/              # Page Object Models
+├── tests/              # Test files organized by feature
+├── utils/              # Shared constants and utilities
+└── playwright.config.ts
+```
+
+## Design Principles
+
+We follow **YAGNI** (You Aren't Gonna Need It), **DRY** (Don't Repeat Yourself), and **KISS** (Keep It Simple, Stupid) principles:
+
+- Build only what's needed now
+- Reuse existing patterns and components
+- Keep solutions simple and maintainable
+
+## Page Object Pattern
+
+Each page object encapsulates:
+
+- **Actions**: What you can do on the page
+- **Queries**: Information you can get from the page
+- **Selectors**: Centralized in private static SELECTORS constant
+- **NO Assertions**: Keep assertions in test files
+
+**Example Page Object:**
+
+```typescript
+export class AuthPage {
+  // Selectors centralized in the page object
+  private static readonly SELECTORS = {
+    LOGIN_FORM: '[data-test="login-form"]',
+    USERNAME_INPUT: '[data-test="username-input"]',
+  } as const;
+
+  // Actions - what you can do
+  async loginWithCredentials(username: string, password: string) {}
+
+  // Queries - information you can get
+  async getCurrentUrl(): Promise<string> {}
+
+  // NO assertions - those belong in tests
+}
+```
+
+**Example Test:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { AuthPage } from '../../pages/AuthPage';
+import { LOGIN } from '../../utils/urls';
+
+test('should login with correct credentials', async ({ page }) => {
+  const authPage = new AuthPage(page);
+  await authPage.goto();
+  await authPage.loginWithCredentials('admin', 'general');
+
+  // Assertions belong in tests, not page objects
+  expect(await authPage.getCurrentUrl()).not.toContain(LOGIN);
+});
+```
+
+## Core Components
+
+Reusable UI interaction classes for common elements (`components/core/`):
+
+- **Form**: Container with properly scoped child element access
+- **Input**: Supports `fill()`, `type()`, and `pressSequentially()` methods
+- **Button**: Standard click, hover, focus interactions
+
+**Usage Example:**
+
+```typescript
+import { Form } from '../components/core';
+
+const loginForm = new Form(page, '[data-test="login-form"]');
+const usernameInput = loginForm.getInput('[data-test="username-input"]');
+await usernameInput.fill('admin');
+```
+
+## Test Reports
+
+Playwright generates multiple reports for better visibility:
+
+```bash
+# View interactive HTML report (opens automatically on failure)
+npm run playwright:report
+# or: npx playwright show-report
+
+# View test trace for debugging failures
+npx playwright show-trace test-results/[test-name]/trace.zip
+```
+
+### Report Types
+
+- **List Reporter**: Shows progress and summary table in terminal
+- **HTML Report**: Interactive web interface with screenshots, videos, and traces
+- **JSON Report**: Machine-readable format in `test-results/results.json`
+- **GitHub Actions**: Annotations in CI for failed tests
+
+### Debugging Failed Tests
+
+When tests fail, Playwright automatically captures:
+
+- **Screenshots** at the point of failure
+- **Videos** of the entire test run
+- **Traces** with timeline and network activity
+- **Error context** with detailed debugging information
+
+All debugging artifacts are available in the HTML report for easy analysis.
+
+## Configuration
+
+- **Config**: `playwright.config.ts` - matches Cypress settings
+- **Base URL**: `http://localhost:8088` (assumes Superset running)
+- **Browsers**: Chrome only for Phase 1 (YAGNI)
+- **Retries**: 2 in CI, 0 locally (matches Cypress)
+
+## Contributing Guidelines
+
+### Adding New Tests
+
+1. **Check existing components** before creating new ones
+2. **Use page objects** for page interactions
+3. **Keep assertions in tests**, not page objects
+4. **Follow naming conventions**: `feature.spec.ts`
+
+### Adding New Components
+
+1. **Follow YAGNI**: Only build what's immediately needed
+2. **Use Locator-based scoping** for proper element isolation
+3. **Support both string selectors and Locator objects** via constructor overloads
+4. **Add to `components/core/index.ts`** for easy importing
+
+### Adding New Page Objects
+
+1. **Centralize selectors** in private static SELECTORS constant
+2. **Import shared constants** from `utils/urls.ts`
+3. **Actions and queries only** - no assertions
+4. **Use existing components** for DOM interactions
+
+## Migration from Cypress
+
+When porting Cypress tests:
+
+1. **Port the logic**, not the implementation
+2. **Use page objects** instead of inline selectors
+3. **Replace `cy.intercept/cy.wait`** with `page.waitForRequest()`
+4. **Use shared constants** from `utils/urls.ts`
+5. **Follow the established patterns** shown in `tests/auth/login.spec.ts`
+
+## Best Practices
+
+- **Centralize selectors** in page objects
+- **Centralize URLs** in `utils/urls.ts`
+- **Use meaningful test descriptions**
+- **Keep page objects action-focused**
+- **Put assertions in tests, not page objects**
+- **Follow the existing patterns** for consistency