Fix managed claude-smart citation links

[yyiilluu]

Summary

• deep-link managed Reflexio citations to profile and playbook item filters when IDs are available
• preserve local dashboard citation URLs and fallback managed list-page behavior for items without IDs
• keep Codex compact markdown citation markers parseable back into cited Reflexio records

Tests

• uv run --project plugin pytest -c plugin/pyproject.toml tests/test_context_format.py tests/test_cs_cite.py
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --project plugin pytest -c plugin/pyproject.toml tests/test_context_format.py tests/test_cs_cite.py tests/test_events.py -k "citation or cited or dashboard or managed_reflexio"
• uv run ruff check --select E501,F401,F821 open_source/claude-smart/plugin/src/claude_smart/context_format.py open_source/claude-smart/plugin/src/claude_smart/cs_cite.py open_source/claude-smart/tests/test_context_format.py open_source/claude-smart/tests/test_cs_cite.py

Summary by CodeRabbit

• New Features

  • Citations now support deep-linking directly to specific Reflexio profiles and playbooks instead of generic list pages.

• Changes

  • Citation link formatting default changed from OSC8 to Markdown on Codex.

• Documentation

  • Updated to reflect new citation deep-linking behavior and Reflexio integration.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e3fd3678-1442-4274-b6e6-1e4e704af10e

📥 Commits

Reviewing files that changed from the base of the PR and between 664e8a4 and 9fa313a.

📒 Files selected for processing (10)

• DEVELOPER.md
• MANAGED_REFLEXIO.md
• plugin/scripts/codex-hook.js
• plugin/scripts/hook_entry.sh
• plugin/src/claude_smart/context_format.py
• plugin/src/claude_smart/cs_cite.py
• tests/test_context_format.py
• tests/test_cs_cite.py
• tests/test_events.py
• tests/test_install_scripts.py

---

📝 Walkthrough

Walkthrough

This PR switches the default citation link style from OSC8 to markdown, implements item-specific reflexio deep links for managed citations, adds markdown link escaping in compact markers, and fixes Python interpreter resolution on Windows, with comprehensive test coverage updates.

Changes

Citation Link Style and Reflexio Deep Linking

Layer / File(s)	Summary
Switch default citation link style to markdown plugin/scripts/codex-hook.js, plugin/scripts/hook_entry.sh, DEVELOPER.md	Default value for CLAUDE_SMART_CITATION_LINK_STYLE changed from osc8 to markdown when unset on codex host; environment variable documentation updated.
Item-specific reflexio deep linking plugin/src/claude_smart/cs_cite.py, plugin/src/claude_smart/context_format.py, MANAGED_REFLEXIO.md	New dashboard_url_token() routing for profiles/playbooks with item IDs; new _rule_url() and _remote_reflexio_item_url() helpers generate direct deep links to reflexio profiles and playbooks using query parameters instead of collection pages; documentation added for managed citation deep-link behavior.
Markdown link rendering in citation markers plugin/src/claude_smart/context_format.py	Added _markdown_link() helper to escape markdown link syntax; updated render_inline_compact_with_registry() and _compact_citation_instruction() to generate escaped markdown links in citation markers when not using OSC8.
Test coverage for citation links and reflexio URLs tests/test_context_format.py, tests/test_cs_cite.py, tests/test_events.py, tests/test_install_scripts.py	Test updates to verify markdown as default link style, item-specific reflexio query-parameter URLs, markdown link escaping in markers, new OSC8 opt-in coverage, and Windows Python resolution on hook entry failure.
Python interpreter resolution on Windows plugin/scripts/hook_entry.sh, tests/test_install_scripts.py	Hook entry script now uses claude_smart_resolve_python to find Python interpreter during install-failure reporting, avoiding python3-only dependency; added Windows-specific test coverage.
Installer test fixture and assertion updates tests/test_install_scripts.py	Various assertion and fixture updates for Reflexio TOML path formatting, venv Python resolution, git command argument formatting, and codex hook SessionStart command fixtures.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ReflexioAI/claude-smart#45: Overlapping changes to citation marker generation and "✨ claude-smart rule applied" link-marker UX in context_format.py (OSC8 vs markdown instruction content).
• ReflexioAI/claude-smart#44: Related changes to CLAUDE_SMART_CITATION_LINK_STYLE default in hook scripts and compact Codex rendering in context_format.py, though in opposite direction.
• ReflexioAI/claude-smart#2: Both PRs modify item real_id usage in reflexio URL generation for playbooks/profiles in context_format.py and cs_cite.py.

Poem

🐰 Deep links now flourish in the markdown glade,
Where items find their homes, no list cascade,
With escaped brackets dancing in the night,
Citation markers shining, oh what delight!
Windows too finds Python, no more to despair. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.53% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Fix managed claude-smart citation links' directly reflects the main objective of deep-linking managed Reflexio citations and fixing their link behavior across the codebase.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/managed-citation-deep-links

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}