docs: add a Persian README

[danialshirali16]

Refs #711 (awaiting the required design-approved label; this PR is kept as a draft).

Adds a complete, manually written Persian translation of the current README at docs/i18n/README.fa.md and adds فارسی to the English README language switcher. Commands, configuration snippets, identifiers, and links are preserved.

Harness coverage

• OpenCode 1: not applicable — documentation-only; no harness-facing code changed.
• OpenCode 2: not applicable — documentation-only; no harness-facing code changed.
• Pi: not applicable — documentation-only; no harness-facing code changed.
• OMP: not applicable — documentation-only; no harness-facing code changed.
• Rust module: not applicable — documentation-only; no harness-facing code changed.

---

Summary by cubic

Adds a Persian translation of the README and links it from the language switcher, making project documentation available to Persian-speaking readers.

• Preserves commands, configuration snippets, identifiers, and links from the English README.

^{Written for commit 1781cf3. Summary will update on new commits.}

Confidence Score: 4/5

The PR appears safe to merge, with three non-blocking documentation fixes.

Findings

1.  Four section links are broken ▶
2.  Command description loses text ▶
3.  Compatibility title stays English ▶

Summary

Adds a Persian translation of the README and links it from the English language switcher.

• Readers can open a Persian version of the Magic Context README.

_{Reviews (1) · Last reviewed commit: "docs: link Persian README" · Reviewed by Greptile}

[github-actions]

#711 has the design-approved label; this PR can be reviewed.

[danialshirali16]

The Persian translation is complete. This PR only adds docs/i18n/README.fa.md and the فارسی link in the root README. All 26 fenced code blocks match the English source, the relative documentation links resolve, and git diff --check is clean.

Could a maintainer apply design-approved to #711, or trivial to this documentation-only PR if appropriate? The PR remains in draft as required by CONTRIBUTING.md.

[cubic-dev-ai]

4 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/i18n/README.fa.md">

<violation number="1" location="docs/i18n/README.fa.md:1">
P3: This file is committed with CRLF line endings, while every other README in `docs/i18n/` and the root `README.md` use LF. Convert the file to LF so line endings match the rest of the docs.</violation>

<violation number="2" location="docs/i18n/README.fa.md:29">
P3: These four shortcuts omit the leading `-` from the GitHub heading IDs for emoji-prefixed sections, so they do not navigate. Prefix each fragment with `-`.</violation>

<violation number="3" location="docs/i18n/README.fa.md:145">
P3: The compatibility section's visible title is still English in this Persian translation; translate the `<summary>` label.</violation>

<violation number="4" location="docs/i18n/README.fa.md:229">
P3: `اجرايش` uses the Arabic yeh (ي). Use the Persian yeh (ی) to match the rest of the file: `اجرای`.</violation>
</file>

<sub>Reply to a comment to ask cubic a question or push back. It learns from your replies.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This file is committed with CRLF line endings, while every other README in docs/i18n/ and the root README.md use LF. Convert the file to LF so line endings match the rest of the docs.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/i18n/README.fa.md, line 1:

<comment>This file is committed with CRLF line endings, while every other README in `docs/i18n/` and the root `README.md` use LF. Convert the file to LF so line endings match the rest of the docs.</comment>

<file context>
@@ -0,0 +1,450 @@
+[English](../../README.md) · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Dansk](README.da.md) · [日本語](README.ja.md) · [Polski](README.pl.md) · [Русский](README.ru.md) · [Bosanski](README.bs.md) · [العربية](README.ar.md) · **فارسی** · [Norsk](README.nb.md) · [Português (Brasil)](README.pt-BR.md) · [ไทย](README.th.md) · [Türkçe](README.tr.md) · [Українська](README.uk.md) · [বাংলা](README.bn.md) · [Ελληνικά](README.el.md) · [Tiếng Việt](README.vi.md)
+
+*این نسخهٔ فارسی بر پایهٔ README انگلیسی نوشته شده است؛ README انگلیسی مرجع اصلی پروژه است و ممکن است به‌روزتر باشد.*
</file context>

[cubic-dev-ai]

P3: اجرايش uses the Arabic yeh (ي). Use the Persian yeh (ی) to match the rest of the file: اجرای.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/i18n/README.fa.md, line 229:

<comment>`اجرايش` uses the Arabic yeh (ي). Use the Persian yeh (ی) to match the rest of the file: `اجرای`.</comment>

<file context>
@@ -0,0 +1,450 @@
+- **نوسازی راهنماها**: موضوع راهنماهای منسوخ را با کد فعلی دوباره بررسی و پاسخ‌هایشان را تازه می‌کند.
+- **یادداشت‌های هوشمند**: یادداشت‌های معوقی را که شرط `surface_condition` آن‌ها برقرار شده ارزیابی می‌کند و موارد آماده را نمایش می‌دهد.
+
+از آنجا که عامل رؤیاپرداز هنگام بی‌کاری اجرا می‌شود، مدل‌های محلی—حتی مدل‌های کند—برای آن مناسب‌اند؛ کسی منتظر نمی‌ماند. هر زمان خواستی با `/ctx-dream` اجرايش کن.
+
+---
</file context>

[cubic-dev-ai]

P3: The compatibility section's visible title is still English in this Persian translation; translate the <summary> label.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/i18n/README.fa.md, line 145:

<comment>The compatibility section's visible title is still English in this Persian translation; translate the `<summary>` label.</comment>

<file context>
@@ -0,0 +1,450 @@
+در پروژه‌ای تازه یا پروژه‌ای که مدت‌ها در جریان بوده یکسان کار می‌کند: نصب کن، محیط اجرا را دوباره راه‌اندازی کن و Magic Context از همان لحظه شروع به ثبت زمینه می‌کند. نشست‌های OpenCode، Pi یا OMP پیش از نصب را به‌صورت عطف‌به‌ماسبق وارد حافظه نمی‌کند.
+
+<details>
+<summary><strong>Compatibility with other context-management plugins</strong></summary>
+
+<br>
</file context>

Suggested change

	<summary><strong>Compatibility with other context-management plugins</strong></summary>
	<summary><strong>سازگاری با افزونه‌های دیگر مدیریت زمینه</strong></summary>

[cubic-dev-ai]

P3: These four shortcuts omit the leading - from the GitHub heading IDs for emoji-prefixed sections, so they do not navigate. Prefix each fragment with -.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/i18n/README.fa.md, line 29:

<comment>These four shortcuts omit the leading `-` from the GitHub heading IDs for emoji-prefixed sections, so they do not navigate. Prefix each fragment with `-`.</comment>

<file context>
@@ -0,0 +1,450 @@
+  <a href="#magic-context-چیست">Magic Context چیست؟</a> ·
+  <a href="#شروع-سریع">شروع سریع</a> ·
+  <a href="#بخشی-از-cortexkit">CortexKit</a> ·
+  <a href="#مدیریت-زمینه">مدیریت زمینه</a> ·
+  <a href="#ثبت-دانش">ثبت دانش</a> ·
+  <a href="#تثبیت-حافظه">تثبیت حافظه</a> ·
</file context>

Suggested change

	<a href="#مدیریت-زمینه">مدیریت زمینه</a> ·
	<a href="#ثبت-دانش">ثبت دانش</a> ·
	<a href="#تثبیت-حافظه">تثبیت حافظه</a> ·
	<a href="#بازیابی">بازیابی</a> ·
	<a href="#-مدیریت-زمینه">مدیریت زمینه</a> ·
	<a href="#-ثبت-دانش">ثبت دانش</a> ·
	<a href="#-تثبیت-حافظه">تثبیت حافظه</a> ·
	<a href="#-بازیابی">بازیابی</a> ·

[greptile-apps]

Four section links are broken

These links omit the leading hyphen that GitHub adds when a heading starts with an emoji. Clicking them will not jump to the intended section. Use #-مدیریت-زمینه, #-ثبت-دانش, #-تثبیت-حافظه, and #-بازیابی, matching the English README’s pattern.

Suggested change

	<a href="#مدیریت-زمینه">مدیریت زمینه</a> ·
	<a href="#ثبت-دانش">ثبت دانش</a> ·
	<a href="#تثبیت-حافظه">تثبیت حافظه</a> ·
	<a href="#بازیابی">بازیابی</a> ·
	<a href="#-مدیریت-زمینه">مدیریت زمینه</a> ·
	<a href="#-ثبت-دانش">ثبت دانش</a> ·
	<a href="#-تثبیت-حافظه">تثبیت حافظه</a> ·
	<a href="#-بازیابی">بازیابی</a> ·

[greptile-apps]

Command description loses text

The unescaped pipe between start and pause creates an extra table cell. GitHub drops cells beyond the two declared columns, so readers lose the pause option and closing parenthesis. Escape the pipe as \|, as in the English source.

Suggested change

	| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` | `pause`) |
	| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` \| `pause`) |

[greptile-apps]

Compatibility title stays English

The compatibility section’s collapsed title remains in English even though its contents are translated. Translate the title too, so Persian readers can recognize and open the guidance about conflicting plugins.

Suggested change

	<summary><strong>Compatibility with other context-management plugins</strong></summary>
	<summary><strong>سازگاری با دیگر افزونه‌های مدیریت زمینه</strong></summary>

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[magic-alfonso]

Thank you, this is approved. I've added design-approved to #711.

We read the whole translation against the English README. It's faithful, and the line at the top about English being the authoritative version is fine to keep. Please make these four small fixes:

1. Commands table, /ctx-embed row (line 271). The pipe in `start` | `pause` lost its backslash, so GitHub splits the row into an extra cell and the pause option disappears. Escape it as the English README does: `start` \| `pause`.
2. Git commit indexing (line 248). «(اختیاری)» says "optional", but English says "opt-in", meaning it's off until you enable it. Something like «نیازمند فعال‌سازی صریح؛ به‌طور پیش‌فرض خاموش» keeps that meaning.
3. Mutation catalogue warning (line 388). «این کار جهش را حذف می‌کند و نتیجهٔ زنده‌مانده را جعلی جلوه می‌دهد.» reads as making a surviving result look fake. English means that checking out source during a replay removes the mutation and causes a false survivor. Suggested: «این کار جهش را حذف می‌کند و باعث می‌شود جهش به‌اشتباه زنده‌مانده گزارش شود.»
4. Amnesia analogy (line 45). «فراموشی پیش‌رونده‌ای» means "progressive amnesia". The English term is anterograde amnesia, the inability to form new memories. Suggested: «فراموشی پیش‌گستر (anterograde amnesia)».

Once those are in, mark the PR ready and we'll merge it after the checks pass.