Add macOS PATH troubleshooting note

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.

dashboard/public/config-data.json

@@ -280,5 +280,5 @@
       }
     ]
   },
-  "lastUpdated": "2026-03-03T23:51:17.900Z"
+  "lastUpdated": "2026-03-06T19:56:21.560Z"
 }

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,15 +470,64 @@ policyengine_versions()
               <h3 className="text-lg font-bold text-gray-900 mb-3">
                 Installation
               </h3>
-              <div className="max-w-[640px]">
+              <div className={installOs === 'win' ? 'max-w-3xl' : 'max-w-[640px]'}>
+                <div className="flex gap-1 bg-gray-100 p-1 rounded-lg w-fit mb-4">
+                  {[
+                    { id: 'mac', label: 'macOS/Linux' },
+                    { id: 'win', label: 'Windows' },
+                  ].map(({ id, label }) => (
+                    <button
+                      key={id}
+                      className={`px-3 py-1.5 rounded-md text-xs font-medium transition ${
+                        installOs === id
+                          ? 'bg-white shadow-sm text-primary-600'
+                          : 'text-gray-500 hover:text-gray-700'
+                      }`}
+                      onClick={() => setInstallOs(id)}
+                    >
+                      {label}
+                    </button>
+                  ))}
+                </div>
                 {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`,
                 })}
+                <p className="text-sm text-gray-400 mt-3">
+                  If the command is not found, open Terminal and run <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">uv tool dir --bin</code>, then replace <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">policyengine-taxsim</code> with the full path shown (e.g. <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">/Users/you/.local/bin/policyengine-taxsim</code>).
+                </p>
               </div>
             </div>
 
+            {/* Upgrading & Version Pinning */}
+            <div className="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
+              <h3 className="text-lg font-bold text-gray-900 mb-3">
+                Upgrading
+              </h3>
+              <p className="text-gray-500 mb-4 text-[15px] leading-relaxed">
+                To upgrade to the latest version:
+              </p>
+              {renderCodeBlock({
+                id: 'upgrade',
+                label: 'Terminal',
+                code: 'uv tool upgrade policyengine-taxsim',
+              })}
+              <h3 className="text-lg font-bold text-gray-900 mb-3 mt-6">
+                Version pinning
+              </h3>
+              <p className="text-gray-500 mb-4 text-[15px] leading-relaxed">
+                For reproducible results, pin to a specific version:
+              </p>
+              {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',
+              })}
+            </div>
+
             {/* Usage with language tabs */}
             <div className="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
               <h3 className="text-lg font-bold text-gray-900 mb-3">
@@ -509,6 +559,11 @@ policyengine_versions()
                   code: usageExamples[activeUsageLang].code,
                 })}
               </div>
+              {['stata', 'sas', 'julia'].includes(activeUsageLang) && (
+                <p className="text-sm text-gray-400 mt-3">
+                  If the command is not found, open Terminal and run <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">uv tool dir --bin</code>, then replace <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">policyengine-taxsim</code> with the full path shown (e.g. <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">/Users/you/.local/bin/policyengine-taxsim</code>).
+                </p>
+              )}
 
               {/* Language-specific extras */}
               {activeUsageLang === 'python' && (

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 = () => {
         <h2 className="text-2xl md:text-3xl font-bold text-secondary-900 text-center mb-8">
           Installation
         </h2>
-        <div className="max-w-[640px] mx-auto">
+        <div className={`${os === 'win' ? 'max-w-3xl' : 'max-w-[640px]'} mx-auto`}>
+          <div className="flex flex-wrap justify-center gap-2 mb-4">
+            {OS_TABS.map(({ id, label }) => (
+              <button
+                key={id}
+                className={`px-4 py-2 rounded-lg font-medium transition ${
+                  os === id
+                    ? 'bg-primary-500 text-white'
+                    : 'bg-white text-gray-500 hover:bg-gray-100'
+                }`}
+                onClick={() => setOs(id)}
+              >
+                {label}
+              </button>
+            ))}
+          </div>
           <CodeBlock
             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={INSTALL_COMMANDS[os]}
             language="cli"
           />
         </div>
@@ -223,6 +247,11 @@ const LandingContent = () => {
               />
             </div>
           </div>
+          {['stata', 'sas', 'julia'].includes(lang) && (
+            <p className="text-sm text-gray-400 mt-6 text-center">
+              If the command is not found, open Terminal and run <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">uv tool dir --bin</code>, then replace <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">policyengine-taxsim</code> with the full path shown (e.g. <code className="bg-gray-100 px-1.5 py-0.5 rounded text-xs">/Users/you/.local/bin/policyengine-taxsim</code>).
+            </p>
+          )}
         </div>
       </section>