DOCS-1823 - Align Claude Code tooling with /docs/contributing

AGENTS.md

@@ -6,6 +6,8 @@ This file is the canonical source of context and guardrails for AI coding agents
 Open-source Sumo Logic documentation site built with Docusaurus 3.
 Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic style guide.
 
+This repo takes contributions from both Sumo Logic employees and external community contributors (see [docs/contributing](https://www.sumologic.com/help/docs/contributing) for the fork-and-PR workflow external contributors follow). Most of this file — the skills, directory conventions, frontmatter rules, and slash commands below — works the same for anyone with the repo cloned and Claude Code installed. The exception is anything under **Jira Rules** and the Jira-specific steps in **Pull Requests**: those require internal Sumo Logic Atlassian access, so external contributors should skip them and follow the plain PR steps in docs/contributing instead.
+
 ## Repository
 @https://github.com/SumoLogic/sumologic-documentation
 
@@ -83,8 +85,8 @@ Before pushing any commit that changes docs content:
 2. Tell the user to confirm the changes appear correctly on the site
 3. Wait for explicit approval before pushing
 
-## Jira Rules
-**CRITICAL**: All Jira operations MUST follow the patterns defined in `.claude/commands/jira.md`.
+## Jira Rules (Sumo Logic internal — requires Atlassian access)
+**CRITICAL**: All Jira operations MUST follow the patterns defined in `.claude/commands/jira.md`. This section applies to Sumo Logic employees only — external contributors don't have access to the internal Jira instance and should skip it.
 
 ### Field Requirements
 - **Assignee**: Do not set manually — Jira Automation assigns based on Technical Area.
@@ -130,8 +132,8 @@ If you change the `/help/llm/` URL structure or add new machine-readable mirror
 
 The sections below apply only to Claude Code. Other agents can ignore them.
 
-### Jira Commands
-All Jira operations MUST follow the patterns defined in `.claude/commands/jira.md`, including the three-approach ticket-creation pattern and Technical Area mappings.
+### Jira Commands (Sumo Logic internal)
+All Jira operations MUST follow the patterns defined in `.claude/commands/jira.md`, including the three-approach ticket-creation pattern and Technical Area mappings. Requires internal Atlassian access — not available to external contributors.
 
 ### Slash Commands
 Primary commands for documentation work. Proactively suggest when context fits — don't wait for the user to ask.

README.md

@@ -13,9 +13,9 @@ Our site is built with [Docusaurus 3](https://docusaurus.io/) and supports React
 
 ## Get involved
 
-We welcome contributions from the community. You can fix a typo, propose new content, or improve existing docs by [opening an issue](https://github.com/SumoLogic/sumologic-documentation/issues/new/choose) or submitting a pull request.
+We welcome contributions from the community. You can fix a typo, propose new content, or improve existing docs by [opening an issue](https://github.com/SumoLogic/sumologic-documentation/issues/new/choose) or submitting a Pull Request (PR).
 
-Browse [existing issues](https://github.com/SumoLogic/sumologic-documentation/issues) before opening a new one — someone may have already reported it.
+Browse [existing issues](https://github.com/SumoLogic/sumologic-documentation/issues) before opening a new one. Someone may have already reported it.
 
 We use [cla-bot](https://colineberhardt.github.io/cla-bot/) to manage our Contributor License Agreement (CLA) process. You will be prompted to sign the CLA on your first contribution.
 
@@ -43,7 +43,7 @@ We use [cla-bot](https://colineberhardt.github.io/cla-bot/) to manage our Contri
 
 Edit files using [Markdown syntax](https://www.sumologic.com/help/docs/contributing/style-guide/#markdown). Keep contributions concise, accurate, and aligned with our [Style Guide](https://www.sumologic.com/help/docs/contributing/style-guide/).
 
-See our [Contributor Guidelines](https://www.sumologic.com/help/docs/contributing/create-edit-doc/#edit-a-doc) for details on Markdown editing, proposing bug fixes, and testing your changes.
+See our [Contributor Guidelines](https://www.sumologic.com/help/docs/contributing/create-edit-doc/#edit-a-doc) for details on Markdown editing, proposing content fixes, and testing your changes.
 
 ## Build locally
 
@@ -55,6 +55,8 @@ yarn start
 
 Any broken links or images will be listed in the output. Fix them, rebuild, and verify before submitting. Press `Ctrl + C` to stop the local server.
 
+We exclusively use [Yarn](https://classic.yarnpkg.com/en/) for all installations and builds. Avoid using NPM commands for package installations or updates.
+
 ## Repo structure
 
 | Path | Contents |
@@ -66,21 +68,21 @@ Any broken links or images will be listed in the output. Fix them, rebuild, and
 | `/blog-csoar` | Cloud SOAR release notes |
 | `/static/img` | Images and media assets |
 | `sidebars.ts` | Left-nav sidebar configuration |
-| `docusaurus.config.ts` | Site configuration |
-| `cid-redirects.json` | Permanent URL redirects (CID mappings) |
+| `docusaurus.config.js` | Site configuration |
+| `cid-redirects.json` | URL redirects and CID mappings |
 
-## For Docs Team contributors
+## Claude Code tooling
 
-This repo includes [Claude Code](https://claude.ai/code) tooling for the Docs Team — slash commands for creating docs, auditing content, managing Jira tickets, and more. See [CLAUDE.md](CLAUDE.md) for the full reference.
+This repo includes [Claude Code](https://claude.ai/code) slash commands for creating docs, auditing content, and more. Most commands work for anyone with the repo cloned, including external contributors. The exception is Jira-related commands, which require internal Sumo Logic Atlassian access and are for Sumo Logic employees only. See [AGENTS.md](AGENTS.md) for the full reference.
 
 ## Publishing
 
-Our docs team reviews issues and pull requests regularly. Response times may vary depending on the backlog.
+Our docs team reviews issues and PRs regularly. Response times may vary depending on the backlog.
 
 Merge times depend on the type of change:
 
-- **Content changes** (`docs/`, `blog-*`, `static/img`) — no hard merge window. We prefer U.S. or India business hours when possible.
-- **Back-end changes** (`src/`, `sidebars.ts`, config files, `.github/`) — merged **Monday–Friday, 7:00am–2:00pm PT** only, when the WebOps team is available.
+- **Content changes** (`docs/`, `blog-*`, `static/img`): no hard merge window. We prefer U.S. or India business hours when possible.
+- **Back-end changes** (`src/`, `sidebars.ts`, config files, `.github/`): merged **Monday–Friday, 7:00am–2:00pm PT** only, when the WebOps team is available.
 
 PRs that mix content and back-end files follow the back-end rules.
 

cid-redirects.json

@@ -90,7 +90,6 @@
   "/docs/contributing/create-document": "/docs/contributing/create-edit-doc",
   "/docs/contributing/edit-doc": "/docs/contributing/create-edit-doc",
   "/docs/contributing/markdown-cheat-sheet": "/docs/contributing/style-guide",
-  "/docs/contributing/templates": "/docs/contributing/templates/generic-doc",
   "/docs/contributing/templates/template-doc": "/docs/contributing/templates/generic-doc",
   "/docs/c2c": "/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework",
   "/Send-Data": "/docs/send-data",

docs/contributing/create-edit-doc.md

@@ -1,21 +1,24 @@
 ---
 id: create-edit-doc
 title: Create or Edit a Doc
-description: Learn how to create or edit a doc, write content in markdown, and submit your changes to our GitHub repository.
+description: Learn how to create or edit a doc, write content in Markdown, and submit your changes to our GitHub repository.
 ---
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import Iframe from 'react-iframe';
 
 Discovered an error in a document? Learn how to submit a fix, along with a comprehensive guide on creating or editing a Sumo Logic document.
 
+:::tip Recommended: Use Claude Code
+If you have [Claude Code](https://claude.ai/code) installed, this repo's `/doc`, `/audit-doc`, and `/seo-audit` slash commands can help you draft and review docs locally against your fork. See the [README](https://github.com/SumoLogic/sumologic-documentation#claude-code-tooling) for the full command list and which ones require internal access.
+:::
+
 ## Prerequisites
 
-import DocPrereq from '../reuse/doc-prerequisites.md';
+import DocPrereq from '../reuse/contributing/doc-prerequisites.md';
 
 <DocPrereq/>
 
-
 ## Quickstart
 
 ### Submit a GitHub Issue
@@ -26,7 +29,7 @@ Before submitting an issue, you can browse our [existing GitHub issues](https://
 
 ### Submit a minor fix
 
-Submitting a minor fix, such as correcting a typo, is very easy and can be done quickly without having to clone or fork your GitHub repository locally. Check out the instructions below.
+You can submit a minor fix, like a typo correction, without cloning or forking the repository locally. Check out the instructions below.
 
 :::training Micro Lesson
 Check out this brief tutorial on how to submit a basic change to our docs.
@@ -61,21 +64,13 @@ This will fork and submit changes to the Docs Team for review.
 
 ### Step 1: Fork the Sumo Docs repository
 
-1. Fork the [Sumo Docs repository](https://github.com/SumoLogic/sumologic-documentation) locally. Remember to sync your fork and update branches as needed.
-   :::tip GitHub tips
-   * [How to fork a repo](https://help.github.com/articles/fork-a-repo/)
-   * [How to sync your fork with branches](https://help.github.com/articles/syncing-a-fork/)
-   :::
-1. Review our [README](https://github.com/SumoLogic/sumologic-documentation#readme) documentation guidelines.
-1. Create a new branch from your forked repo using a name that best describes the work or references a GitHub issue number. For example, if you wanted to submit a PR to edit our Elasticsearch app doc, you'd write something like: `<your initials>-apps-elasticsearch`.
-
-import Tools from '../reuse/contributing/tools.md';
+import ForkRepo from '../reuse/contributing/fork-repo.md';
 
-<Tools/>
+<ForkRepo/>
 
 ### Step 2: Edit your doc
 
-In your new branch, edit the doc markdown file. See our [Style Guide](/docs/contributing/style-guide) to learn how to style content, add code snippets, import multimedia, and more. Doc body text content is written in GitHub-flavored markdown, with some customizations.
+In your new branch, edit the doc Markdown file. See our [Style Guide](/docs/contributing/style-guide) to learn how to style content, add code snippets, import multimedia, and more. Doc body text content is written in GitHub-flavored Markdown, with some customizations.
 
 ### Step 3: Preview your changes
 
@@ -89,37 +84,30 @@ In your new branch, edit the doc markdown file. See our [Style Guide](/docs/cont
 
 To submit more extensive edits, such as creating a new doc, we recommend forking our repo, making changes in a new branch, and submitting a PR for review.
 
-Feel free to [reach out to the Docs Team](#contact-us) to discuss. We're happy to work with you on the project and talk through rewriting content, changing flow, adding a new topic or section, and deprecating content.
+Feel free to [reach out to the Sumo Logic Docs Team](#contact-us) to discuss. We're happy to work with you on the project and talk through rewriting content, changing flow, adding a new topic or section, and deprecating content.
 
 ### Step 1: Fork the Sumo Docs repository
 
-import ForkRepo from '../reuse/contributing/fork-repo.md';
-
 <ForkRepo/>
 
-<Tools/>
-
 ### Step 2: Create a doc file
 
-Our docs are GitHub-flavored markdown files containing content like bulleted instructions, screenshots, tables, interactive code samples, and more.
+Our docs are GitHub-flavored Markdown files containing content like bulleted instructions, screenshots, tables, interactive code samples, and more.
 
 1. Open your new branch in your IDE and go to the `/docs` folder.
-1. Create a new markdown file in the format `<your-file>.md` and save it to the appropriate subfolder. For example, if you're creating a new metrics doc, you'd save it to the `/docs/metrics` folder.
+1. Create a new Markdown file in the format `<your-file>.md` and save it to the appropriate subfolder. For example, if you're creating a new metrics doc, you'd save it to the `/docs/metrics` folder.
 1. At the top of your file, add your frontmatter, which is the doc metadata. Follow the instructions under [Frontmatter](/docs/contributing/style-guide/#metadata-frontmatter), and see [Metadata descriptions](/docs/contributing/style-guide/#metadata-descriptions) for description length and formatting rules.
 
-
 ### Step 3: Write your doc
 
-In your Integrated Development Environment (IDE), compose the body of your document.
-
-Refer to our [Style Guide](/docs/contributing/style-guide) for instructions on crafting and styling content, including adding code snippets, importing multimedia, and more. The body text of your document is written in GitHub-flavored markdown, with some customizations.
+In your Integrated Development Environment (IDE), compose the body of your document in GitHub-flavored Markdown. Refer to our [style guide](/docs/contributing/style-guide) for instructions on crafting and styling content, including adding code snippets, importing multimedia, and more.
 
 ### Step 4: Add doc to the navigation menu
 
 To add your new doc to the left-nav menu, you'll need to add its name and file path to the [`sidebars.ts` file](https://github.com/SumoLogic/sumologic-documentation/blob/main/sidebars.ts).
 
-:::note Doc Team Support
-The Sumo Logic Doc Team can help you add your doc to the sidebar and top navigation. If you have suggestions, include those in your Pull Request description. If you add the documentation to the sidebar, the team will review the location and names for building and placement in navigation.
+:::note Docs Team Support
+The Docs Team can help you add your doc to the sidebar and top navigation. If you have suggestions, include those in your PR description. If you add the documentation to the sidebar, the team will review the location and names for building and placement in navigation.
 :::
 
 ### Step 5: Add doc to the hub page
@@ -132,12 +120,12 @@ Once you decide on placement, use the card HTML code in that doc to create a new
 
 ### Step 6: Create CID URL
 
-We often encounter changes in links, so we assign each document a permanent URL, which includes a Content ID (CID) number. This permanent URL performs a 301 redirect to the canonical URL. This approach ensures that future modifications to the canonical URL, such as product name changes, do not affect the 'Learn More' links for users. Additionally, it reduces the need for code changes to the user interface, offering greater flexibility for making quick updates.
+We assign each document a permanent URL with a content ID (CID) number, which performs a 301 redirect to the canonical URL. This means future changes to the canonical URL, such as a product name change, won't break **Learn More** links or require code changes to the user interface.
 
 This URL is then placed in the UI in the appropriate place. For example, `cid=0071` links to a metrics page, which appears in the product in the **Metrics** section as a help link.
 
 To create a CID:
-1. In your GitHub authoring tool (like Atom or VS Code), open our [cid-redirects.json file](https://github.com/SumoLogic/sumologic-documentation/blob/main/cid-redirects.json), which contains all 301 redirects.
+1. In a GitHub authoring tool like VS Code, open our [cid-redirects.json file](https://github.com/SumoLogic/sumologic-documentation/blob/main/cid-redirects.json), which contains all 301 redirects.
 1. Scroll down to the CIDs section, where the line items start with `"/cid/"`.
 1. Find an unused CID number, then associate that CID value to your doc's file path. For example, if `5122` is unused, and your file path is `/docs/metrics/chart`:
   ```json title="Example" {2}
@@ -163,22 +151,10 @@ import Submit from '../reuse/contributing/submit.md';
 
 ## What happens next?
 
-Docs Team members will review contributions, provide feedback, and approve. When approved, the Docs Team will merge and update staging. Updates to production will be handled by the Docs Team.
+The Docs Team will review contributions, provide feedback, and merge approved changes to staging. They'll handle production updates separately.
 
 ## Contact us
 
 Need to get in touch? You can find us at:
 * [Sumo Logic Support](https://support.sumologic.com/support/s)
 * [Sumo Logic Community](https://sumologic.my.site.com/support/s/)
-* [Sumo Dojo Slack](https://sumodojo.slack.com)
-
-
-<!--
-#### Pull Request Submission Guidelines
-
-We currently cut branches from <code>main</code> for accepting documentation. As our processes refine and work expands, we may use the [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) for development content.
-
-As PRs are merged to the main branch by the Sumo Logic Docs Team, the content builds and deploys to a staging site. This can be reviewed and tested thoroughly on a server, rather than a local.
-
-When all content is tested and ready for live, a Sumo Logic Docs Team member can tag a release to build and deploy to Production. This site is live to the world to search, use, and read to learn Sumo Logic.
--->