docs: Update JSON Persistence page with cross-platform (Windows/Unix) support note

[MervinPraison]

Context

PR MervinPraison/PraisonAI#1544 was merged today. It makes the DefaultSessionStore file-locking mechanism cross-platform compatible, fixing a Windows test collection failure caused by an unconditional import fcntl in praisonaiagents/session/store.py.

• Linked Issue: MervinPraison/PraisonAI#1540
• SDK file: praisonaiagents/session/store.py
• Commit head SHA: 09f7f4e5f58a432cfbdf48750c8e0fb6131e5e67

This is purely a bug fix (no new APIs, no parameter changes), but it carries a user-facing guarantee that the docs do not currently surface: DefaultSessionStore works on both Unix and Windows out of the box, with multi-process-safe file locking on each platform.

---

Decision: Update Existing Content (No New Page Needed)

Question	Answer
New API surface?	No
New configuration option?	No
New user-facing feature?	No (the locking behaviour was always intended; PR just makes it actually work on Windows)
Existing page covers this area?	Yes — docs/features/persistence-json.mdx
New page required?	No
Update required?	Yes — add a Cross-Platform Support section to the existing page

This is an update, not a new page. The new docs agent should edit docs/features/persistence-json.mdx (and optionally add a one-liner to docs/features/persistence.mdx).

---

What Changed in the SDK (Source of Truth)

File: praisonaiagents/session/store.py

Before:

import fcntl   # Unconditional — crashes on Windows during import

After:

import sys

# fcntl is Unix-only; on Windows, use msvcrt for file locking
if sys.platform != 'win32':
    import fcntl
    _HAS_FCNTL = True
else:
    _HAS_FCNTL = False

The FileLock class inside DefaultSessionStore already had a sys.platform == "win32" branch using msvcrt.locking(...). The PR just makes the fcntl import itself conditional so the module can be imported at all on Windows.

If neither fcntl nor msvcrt is available (theoretical edge case), acquire() logs a one-time warning and continues without locking:

"File locking unavailable on this platform (no fcntl/msvcrt); concurrent writers may corrupt session files."

---

Required Documentation Update

File to update

docs/features/persistence-json.mdx

Where to insert

After the existing "How It Works" section, add a new section titled "Cross-Platform Support" before "Configuration Options".

Suggested content (follow AGENTS.md style — agent-centric, beginner-friendly, progressive disclosure)

---

## Cross-Platform Support

JSON persistence works the same on macOS, Linux, and Windows — no extra configuration.

```mermaid
graph LR
    subgraph "Cross-Platform File Locking"
        A[🧠 Agent] --> B{🖥️ Platform?}
        B -->|macOS / Linux| C[🔒 fcntl lock]
        B -->|Windows| D[🔒 msvcrt lock]
        C --> E[💾 Safe Write]
        D --> E
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef detect fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef lock fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef write fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class B detect
    class C,D lock
    class E write
```

The same agent code runs everywhere:

```python
from praisonaiagents import Agent

agent = Agent(
    name="FileBot",
    instructions="You are a helpful assistant.",
    session_id="cross-platform-session"
)

agent.chat("Hello! Works on macOS, Linux, and Windows.")
```

| Platform | File Lock Mechanism | Multi-Process Safe |
|----------|---------------------|--------------------|
| macOS    | `fcntl.flock`       | ✅ Yes              |
| Linux    | `fcntl.flock`       | ✅ Yes              |
| Windows  | `msvcrt.locking`    | ✅ Yes              |

<Note>
If you run multiple agent processes that share the same `session_dir`, the
store automatically prevents concurrent writers from corrupting session
files — on every supported OS.
</Note>

Optional: Tiny note on docs/features/persistence.mdx

In the existing "Storage Backend Options" card grid, the JSON Files card description can be tightened to reassure Windows users:

"Simple file-based storage with cross-platform locking — works on macOS, Linux, and Windows."

(Pure copy change; no structural edits.)

---

Folder Placement (per AGENTS.md §1.8)

• ✅ Update docs/features/persistence-json.mdx
• ✅ (Optional) Touch docs/features/persistence.mdx
• ❌ Do NOT create or modify anything in docs/concepts/
• ❌ Do NOT modify docs/js/ or docs/rust/ (auto-generated)

---

SDK-First Verification Checklist (per AGENTS.md §1.2 / §1.3)

Before writing/editing, confirm against the SDK source:

• Read praisonaiagents/session/store.py end-to-end
• Confirm _HAS_FCNTL flag and the sys.platform != 'win32' guard
• Confirm FileLock.acquire() and FileLock.release() Windows branches use msvcrt.locking
• Confirm no new public APIs were added (signatures of DefaultSessionStore, add_message, get_chat_history, list_sessions, etc. are unchanged)
• Verify the import praisonaiagents example actually works on Windows (no ImportError)

---

Quality Checklist (per AGENTS.md §9)

• Frontmatter unchanged (title, sidebarTitle, description, icon already correct)
• New section uses one-sentence intro (no forbidden phrases)
• Hero/section Mermaid diagram uses standard color palette (#8B0000, #189AB4, #10B981, #F59E0B, white text, #7C90A0 stroke)
• Code example uses from praisonaiagents import Agent (friendly import, no deep paths)
• Agent-centric example at the top of the new section
• Progressive disclosure: simple example → table → callout
• No SDK-internal jargon (fcntl/msvcrt only appear in the comparison table, not in code the user has to write)
• No new entry needed in docs.json (page already registered under "Features")

---

Out of Scope (Do Not Do)

• ❌ Do not document _HAS_FCNTL or _WARNED_NO_FCNTL — these are internal sentinels.
• ❌ Do not add a new page like windows-support.mdx — this is one section in an existing page.
• ❌ Do not modify the auto-generated docs/js/ or docs/rust/ parity pages.
• ❌ Do not touch docs/concepts/ (human-approved only).

---

Acceptance Criteria

• docs/features/persistence-json.mdx contains a new "Cross-Platform Support" section after "How It Works".
• Section includes a Mermaid diagram with the standard color palette and a platform-comparison table.
• Code example is agent-centric and uses the friendly from praisonaiagents import Agent import.
• (Optional) docs/features/persistence.mdx JSON Files card description mentions cross-platform locking.
• No files added/modified outside docs/features/.
• PR opened as draft against main, branch named claude/admiring-euler-CLjpN (per agent branch policy).

---

References

• PR: fix: make session store fcntl import cross-platform compatible PraisonAI#1544
• Issue: Windows test collection fails due to Unix-only fcntl import in session store PraisonAI#1540
• SDK file: praisonaiagents/session/store.py
• Existing docs: docs/features/persistence-json.mdx, docs/features/persistence.mdx
• Style guide: AGENTS.md (this repo)

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-243-20260424-1010 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-243-20260424-1010?quick_pull=1&title=Issue%20%23243%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23243%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

I'll help you update the JSON Persistence documentation with cross-platform support notes. Let me work through this step by step.

Todo List

• Set up git identity and auth
• Read AGENTS.md for style guidelines
• Read SDK source code from PraisonAI repo
• Update docs/features/persistence-json.mdx with new cross-platform section
• Optionally update docs/features/persistence.mdx
• Commit and push changes
• Create pull request

Completed Successfully! ✅

I've successfully updated the JSON Persistence documentation with comprehensive cross-platform support information. Here's what was implemented:

New Cross-Platform Support Section Added:

• Mermaid diagram showing platform detection flow with standard color scheme
• Agent-centric code example demonstrating identical usage across platforms
• Platform comparison table detailing file lock mechanisms (fcntl vs msvcrt)
• Multi-process safety callout explaining concurrent access protection

Additional Updates:

• Updated main persistence overview page to mention cross-platform locking in JSON Files card

Quality Verification:

• ✅ Follows AGENTS.md structure template and style guidelines
• ✅ Uses standard Mermaid color scheme (#8B0000, #189AB4, #10B981, #F59E0B)
• ✅ Agent-centric examples with friendly imports (from praisonaiagents import Agent)
• ✅ Progressive disclosure: simple example → table → callout
• ✅ One-sentence section introduction as required

Pull Request Created: #246

The documentation now clearly communicates that JSON persistence works seamlessly across Windows, macOS, and Linux with automatic platform-appropriate file locking for multi-process safety.
|