From 9557d4f72ba87d10677ed600f0ef18a6e092c7f7 Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Thu, 5 Mar 2026 02:19:59 +0100 Subject: [PATCH 1/5] Add macOS PATH troubleshooting note to install sections On macOS, Stata/SAS launch non-interactive shells that don't load ~/.zshrc, so uv-installed tools aren't on the PATH. Add a note pointing users to the full path ~/.local/bin/policyengine-taxsim. Co-Authored-By: Claude Opus 4.6 --- changelog.d/fix-path-troubleshooting.fixed.md | 1 + dashboard/src/components/DocumentationContent.jsx | 4 ++++ dashboard/src/components/LandingContent.jsx | 4 ++++ 3 files changed, 9 insertions(+) create mode 100644 changelog.d/fix-path-troubleshooting.fixed.md diff --git a/changelog.d/fix-path-troubleshooting.fixed.md b/changelog.d/fix-path-troubleshooting.fixed.md new file mode 100644 index 0000000..bd09ab4 --- /dev/null +++ b/changelog.d/fix-path-troubleshooting.fixed.md @@ -0,0 +1 @@ +Add macOS troubleshooting note for PATH issues when using policyengine-taxsim from Stata, SAS, or other programs. diff --git a/dashboard/src/components/DocumentationContent.jsx b/dashboard/src/components/DocumentationContent.jsx index 49b6162..455b0a5 100644 --- a/dashboard/src/components/DocumentationContent.jsx +++ b/dashboard/src/components/DocumentationContent.jsx @@ -475,6 +475,10 @@ policyengine_versions() label: 'Terminal', code: `# Install uv package manager (if you don't have it)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim`, })} +

+ macOS note: If Stata, SAS, or other programs can't find the command, use the full + path: ~/.local/bin/policyengine-taxsim +

diff --git a/dashboard/src/components/LandingContent.jsx b/dashboard/src/components/LandingContent.jsx index 888b529..e3bc3be 100644 --- a/dashboard/src/components/LandingContent.jsx +++ b/dashboard/src/components/LandingContent.jsx @@ -174,6 +174,10 @@ const LandingContent = () => { } language="cli" /> +

+ macOS note: If Stata, SAS, or other programs can't find the command, use the full + path: ~/.local/bin/policyengine-taxsim +

From 5cd0f790ae8734d262d6e405a1a681bc63acb0b5 Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Thu, 5 Mar 2026 14:40:01 +0100 Subject: [PATCH 2/5] Refine macOS PATH troubleshooting note Show note only for Stata/SAS/Julia tabs and use direct documentation tone: "Replace X with Y if the command is not found." Co-Authored-By: Claude Opus 4.6 --- dashboard/src/components/DocumentationContent.jsx | 3 +-- dashboard/src/components/LandingContent.jsx | 9 +++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/dashboard/src/components/DocumentationContent.jsx b/dashboard/src/components/DocumentationContent.jsx index 455b0a5..6bf1289 100644 --- a/dashboard/src/components/DocumentationContent.jsx +++ b/dashboard/src/components/DocumentationContent.jsx @@ -476,8 +476,7 @@ policyengine_versions() code: `# Install uv package manager (if you don't have it)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim`, })}

- macOS note: If Stata, SAS, or other programs can't find the command, use the full - path: ~/.local/bin/policyengine-taxsim + macOS: Replace policyengine-taxsim with ~/.local/bin/policyengine-taxsim if the command is not found.

diff --git a/dashboard/src/components/LandingContent.jsx b/dashboard/src/components/LandingContent.jsx index e3bc3be..0514e7b 100644 --- a/dashboard/src/components/LandingContent.jsx +++ b/dashboard/src/components/LandingContent.jsx @@ -174,10 +174,6 @@ const LandingContent = () => { } language="cli" /> -

- macOS note: If Stata, SAS, or other programs can't find the command, use the full - path: ~/.local/bin/policyengine-taxsim -

@@ -227,6 +223,11 @@ const LandingContent = () => { /> + {['stata', 'sas', 'julia'].includes(lang) && ( +

+ macOS: Replace policyengine-taxsim with ~/.local/bin/policyengine-taxsim if the command is not found. +

+ )} From dbeb87236ed7233250aa8e413869727267963df2 Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Thu, 5 Mar 2026 18:33:17 +0100 Subject: [PATCH 3/5] Use platform-agnostic PATH troubleshooting note Replace macOS-specific ~/.local/bin path with universal instructions: run `uv tool dir --bin` to find the correct path on any OS. Co-Authored-By: Claude Opus 4.6 --- dashboard/src/components/DocumentationContent.jsx | 2 +- dashboard/src/components/LandingContent.jsx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dashboard/src/components/DocumentationContent.jsx b/dashboard/src/components/DocumentationContent.jsx index 6bf1289..d739c72 100644 --- a/dashboard/src/components/DocumentationContent.jsx +++ b/dashboard/src/components/DocumentationContent.jsx @@ -476,7 +476,7 @@ policyengine_versions() code: `# Install uv package manager (if you don't have it)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim`, })}

- macOS: Replace policyengine-taxsim with ~/.local/bin/policyengine-taxsim if the command is not found. + If the command is not found, open Terminal and run uv tool dir --bin, then replace policyengine-taxsim with the full path shown (e.g. /Users/you/.local/bin/policyengine-taxsim).

diff --git a/dashboard/src/components/LandingContent.jsx b/dashboard/src/components/LandingContent.jsx index 0514e7b..0e997dd 100644 --- a/dashboard/src/components/LandingContent.jsx +++ b/dashboard/src/components/LandingContent.jsx @@ -225,7 +225,7 @@ const LandingContent = () => { {['stata', 'sas', 'julia'].includes(lang) && (

- macOS: Replace policyengine-taxsim with ~/.local/bin/policyengine-taxsim if the command is not found. + If the command is not found, open Terminal and run uv tool dir --bin, then replace policyengine-taxsim with the full path shown (e.g. /Users/you/.local/bin/policyengine-taxsim).

)} From f91c7ea9a73d90656c0502ae3a0c351be9dfd447 Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Fri, 6 Mar 2026 20:58:41 +0100 Subject: [PATCH 4/5] Add OS tabs to Installation sections for Windows support Co-Authored-By: Claude Opus 4.6 --- dashboard/public/config-data.json | 2 +- .../src/components/DocumentationContent.jsx | 27 ++++++++++++++-- dashboard/src/components/LandingContent.jsx | 32 ++++++++++++++++--- 3 files changed, 53 insertions(+), 8 deletions(-) diff --git a/dashboard/public/config-data.json b/dashboard/public/config-data.json index bab72ba..41a8b76 100644 --- a/dashboard/public/config-data.json +++ b/dashboard/public/config-data.json @@ -280,5 +280,5 @@ } ] }, - "lastUpdated": "2026-03-03T23:51:17.900Z" + "lastUpdated": "2026-03-06T19:56:21.560Z" } \ No newline at end of file diff --git a/dashboard/src/components/DocumentationContent.jsx b/dashboard/src/components/DocumentationContent.jsx index d739c72..df1971d 100644 --- a/dashboard/src/components/DocumentationContent.jsx +++ b/dashboard/src/components/DocumentationContent.jsx @@ -80,6 +80,7 @@ const DocumentationContent = () => { }; const [activeUsageLang, setActiveUsageLang] = useState('cli'); + const [installOs, setInstallOs] = useState('mac'); const usageExamples = { cli: { @@ -469,11 +470,31 @@ policyengine_versions()

Installation

-
+
+
+ {[ + { id: 'mac', label: 'macOS/Linux' }, + { id: 'win', label: 'Windows' }, + ].map(({ id, label }) => ( + + ))} +
{renderCodeBlock({ - id: 'install-pip', + id: `install-${installOs}`, label: 'Terminal', - code: `# Install uv package manager (if you don't have it)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim`, + code: installOs === 'mac' + ? `# Install uv package manager (if you don't have it)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim` + : `# Install uv package manager (if you don't have it)\npowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim`, })}

If the command is not found, open Terminal and run uv tool dir --bin, then replace policyengine-taxsim with the full path shown (e.g. /Users/you/.local/bin/policyengine-taxsim). diff --git a/dashboard/src/components/LandingContent.jsx b/dashboard/src/components/LandingContent.jsx index 0e997dd..0d27bf3 100644 --- a/dashboard/src/components/LandingContent.jsx +++ b/dashboard/src/components/LandingContent.jsx @@ -140,8 +140,19 @@ const COMPARISON_EXAMPLES = { }, }; +const OS_TABS = [ + { id: 'mac', label: 'macOS/Linux' }, + { id: 'win', label: 'Windows' }, +]; + +const INSTALL_COMMANDS = { + mac: "# Install uv package manager (if you don't have it)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim", + win: "# Install uv package manager (if you don't have it)\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Install policyengine-taxsim\nuv tool install policyengine-taxsim", +}; + const LandingContent = () => { const [lang, setLang] = useState('cli'); + const [os, setOs] = useState('mac'); const example = COMPARISON_EXAMPLES[lang]; @@ -166,12 +177,25 @@ const LandingContent = () => {

Installation

-
+
+
+ {OS_TABS.map(({ id, label }) => ( + + ))} +
From 2788dc14253503404a12eefcb1bca1dae08d475a Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Fri, 6 Mar 2026 21:14:42 +0100 Subject: [PATCH 5/5] Add upgrading, version pinning, and usage PATH note to docs Co-Authored-By: Claude Opus 4.6 --- .../src/components/DocumentationContent.jsx | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/dashboard/src/components/DocumentationContent.jsx b/dashboard/src/components/DocumentationContent.jsx index df1971d..77647f5 100644 --- a/dashboard/src/components/DocumentationContent.jsx +++ b/dashboard/src/components/DocumentationContent.jsx @@ -470,7 +470,7 @@ policyengine_versions()

Installation

-
+
{[ { id: 'mac', label: 'macOS/Linux' }, @@ -502,6 +502,32 @@ policyengine_versions()
+ {/* Upgrading & Version Pinning */} +
+

+ Upgrading +

+

+ To upgrade to the latest version: +

+ {renderCodeBlock({ + id: 'upgrade', + label: 'Terminal', + code: 'uv tool upgrade policyengine-taxsim', + })} +

+ Version pinning +

+

+ For reproducible results, pin to a specific version: +

+ {renderCodeBlock({ + id: 'version-pin', + label: 'Terminal', + code: '# Install a specific version of policyengine-taxsim\nuv tool install policyengine-taxsim==2.13.0\n\n# Pin the underlying tax model for reproducible results\nuv tool install policyengine-taxsim --with policyengine-us==1.555.0', + })} +
+ {/* Usage with language tabs */}

@@ -533,6 +559,11 @@ policyengine_versions() code: usageExamples[activeUsageLang].code, })}

+ {['stata', 'sas', 'julia'].includes(activeUsageLang) && ( +

+ If the command is not found, open Terminal and run uv tool dir --bin, then replace policyengine-taxsim with the full path shown (e.g. /Users/you/.local/bin/policyengine-taxsim). +

+ )} {/* Language-specific extras */} {activeUsageLang === 'python' && (