docs: clarify platform support and command usage

Author: bitfalt

CONTRIBUTING.md

@@ -44,6 +44,11 @@ git clone https://github.com/DojoCodingLabs/code-sensei.git
 cd code-sensei
 ```
 
+Supported development environments:
+- macOS
+- Linux
+- Windows via WSL
+
 ### Testing Locally
 ```bash
 # Open Claude Code

PRIVACY.md

@@ -4,6 +4,10 @@ CodeSensei is designed to be local-first.
 
 This document explains what the plugin stores on disk, what it does not do, and how retention works.
 
+Platform note:
+- CodeSensei currently targets macOS and Linux shells.
+- On Windows, use WSL for the most reliable behavior.
+
 ## What CodeSensei stores locally
 
 By default, CodeSensei writes data under:

README.md

@@ -57,8 +57,18 @@ Instead of forcing people to stop building and go study in a separate environmen
 
 `jq` is required for profile tracking, imports, quizzes, and diagnostics.
 
+### Supported platforms
+
+- ✅ macOS
+- ✅ Linux
+- ⚠️ Windows via WSL recommended
+
+CodeSensei is a Unix-shell plugin today. Its runtime depends on `bash`, `jq`, and standard Unix tools, so WSL is the safest path on Windows.
+
 ### Install from marketplace
 
+Inside Claude Code:
+
 ```bash
 /plugin marketplace add DojoCodingLabs/code-sensei
 /plugin install code-sensei@code-sensei
@@ -76,9 +86,11 @@ After install:
 
 ### Update
 
+Inside Claude Code:
+
 ```bash
-claude plugin marketplace update DojoCodingLabs/code-sensei
-claude plugin update code-sensei@code-sensei
+/plugin marketplace update DojoCodingLabs/code-sensei
+/plugin update code-sensei@code-sensei
 ```
 
 Restart your Claude Code session after updating so hooks reload cleanly.

docs/plans/2026-03-19-marketplace-readiness.md

@@ -77,3 +77,23 @@
 - [ ] Hook regression tests pass locally
 - [ ] CI runs critical hook tests
 - [ ] Repo is clean and pushed to `main`
+
+---
+
+## Follow-up production hardening (reviewer notes)
+
+These items were identified in the final marketplace review and should be addressed as part of ongoing production readiness:
+
+1. **Supported platform clarity**
+   - Make README/listing docs explicit that CodeSensei supports macOS and Linux.
+   - Clarify that Windows users should use WSL unless native Windows support is added later.
+
+2. **Command-surface consistency**
+   - Use one consistent “inside Claude Code” command style in README examples for install/update flows.
+
+3. **Expanded behavioral test coverage**
+   - Add regression coverage for `scripts/session-start.sh`.
+   - Add regression coverage for `scripts/export-profile.sh`.
+
+4. **macOS CI smoke coverage**
+   - Add a lightweight `macos-latest` GitHub Actions job that installs `jq`, runs key shell smoke/behavior tests, and validates the Unix-shell support claim.