Agent docs -- GitHub actions

AGENTS.md

@@ -2,6 +2,12 @@
 
 This file provides detailed guidance for AI agents and automated tools working with the Lexical codebase.
 
+## Documentation
+
+For specialized topics, see the [`docs/`](./docs/) directory:
+
+- **[GitHub Actions Security & Architecture](./docs/github-actions.md)** - Guidelines for CI/CD workflows, security practices, permissions, and secrets management
+
 ## Build, Test, and Development Commands
 
 ### Building
@@ -130,6 +136,23 @@ When adding/modifying APIs, types must be maintained for both systems.
 
 ## Important Development Notes
 
+### Package Manager Usage
+
+This repository uses different package managers for different contexts:
+
+**Development and CI workflows** - Use `pnpm`:
+- The monorepo is managed with pnpm workspaces
+- All CI/CD workflows use pnpm
+- Run `pnpm install` to install dependencies
+- Run `pnpm run <script>` for development commands
+
+**Example projects and integration tests** - Use `npm`:
+- Examples are user-facing and should be package-manager agnostic
+- Integration tests simulate real user workflows with npm
+- Examples have their own `package.json` and may use `npm` or `package-lock.json`
+
+See [docs/github-actions.md](./docs/github-actions.md#package-manager-usage) for detailed rationale.
+
 ### Reconciliation and Updates
 - `editor.read()` flushes pending updates first, then provides consistent reconciled state
 - Inside `editor.update()`, you see pending state (transforms/reconciliation not yet run)

docs/README.md

@@ -0,0 +1,33 @@
+# Lexical Documentation
+
+This directory contains specialized documentation for the Lexical project.
+
+## Available Documentation
+
+### [GitHub Actions Security & Architecture](./github-actions.md)
+
+Comprehensive guide to the repository's CI/CD approach, including:
+- Security principles and best practices
+- Workflow categorization (test vs. release vs. publish)
+- Secrets management
+- Guidelines for adding new workflows
+- Package manager usage (pnpm vs. npm)
+- Troubleshooting common issues
+
+**Audience**: Contributors adding or modifying GitHub Actions workflows, security reviewers, and agents/tools working with CI/CD.
+
+## Contributing to Documentation
+
+When adding new documentation:
+
+1. Create a new `.md` file in this directory
+2. Add it to this README with a brief description
+3. Link to it from relevant files (e.g., AGENTS.md, CONTRIBUTING.md)
+4. Follow the existing documentation structure and style
+5. Include practical examples and rationale for decisions
+
+## Related Documentation
+
+- **[AGENTS.md](../AGENTS.md)** - Guide for AI agents and automated tools working with the codebase
+- **[Maintainers' Guide](../packages/lexical-website/docs/maintainers-guide.md)** - Monorepo organization, package management, release procedures
+- **[Contributing Guide](../CONTRIBUTING.md)** - Guidelines for contributing to Lexical