MASQ-Project · kauri-hero · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -0,0 +1,24 @@
+/** @type {import('eslint').Linter.Config} */
+module.exports = {
+  root: true,
+  extends: ['plugin:@docusaurus/recommended'],
+  env: {
+    browser: true,
+    node: true,
+    es2022: true,
+  },
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+  ignorePatterns: [
+    'build/',
+    '.docusaurus/',
+    'node_modules/',
+    'working-docs/',
+    'gitbook-src/',
+  ],
+};
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -19,6 +19,8 @@ jobs:
           cache: npm
       - name: Install dependencies
         run: npm ci
+      - name: Lint
+        run: npm run lint
       - name: Build website
         run: npm run build
       - name: Upload Build Artifact

diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml
@@ -23,5 +23,7 @@ jobs:
           cache: npm
       - name: Install dependencies
         run: npm ci
+      - name: Lint
+        run: npm run lint
       - name: Test build website
         run: npm run build
diff --git a/AGENTS.md b/AGENTS.md
@@ -140,5 +140,5 @@ When continuing polish / visual QA (see `working-docs/HANDOVER-HARDENING.md` if
 ```powershell
 git status -sb
 npm run build
-# spot-check: npm start → /, /masq-web3-privacy-browser, /resources/installer-checksums
+# spot-check: npm start → /, /masq-privacy-browser, /resources/installer-checksums
 ```
diff --git a/docs/advanced-use/cli-startup-guides/index.mdx b/docs/advanced-use/cli-startup-guides/index.mdx
@@ -1,11 +1,15 @@
+import DocCardList from '@theme/DocCardList';
+
 # CLI Startup Guides
 
-This are targeting to Quality Assurance (QA) testing for our development, but will be helpful for you to prepare your machine to run from Command Line (CLI)
+These guides target Quality Assurance (QA) testing for our development, but they also help you prepare a machine to run MASQ from the command line (CLI).
 
 :::warning
 
 Running MASQ from CLI **will** require technical knowledge and possibly adjustments to the network adaptor settings.
 
 MASQ and the developers are not responsible for any issues that arise from user changes to their environment or machine!
 
-:::
+:::
+
+<DocCardList />
diff --git a/docs/advanced-use/cli-startup-guides/masq-cli-linux.mdx b/docs/advanced-use/cli-startup-guides/masq-cli-linux.mdx
@@ -25,15 +25,15 @@ If you have previously tested MASQ Node you need to DELETE ALL OLD NODE DATABASE
 
 Open the file manager and create a new folder named Masq in your home directory
 
-![](/img/assets/grpwmez0x_mvfni_2ghr6jm5gy6l3vjsiwbexc9nb7epjzgm6d4m5mbbj4vxepytpp538dyb2997qsl0vo-sgzy0nge9cn6ukw9khgixj3asrbxgjneo_lsob7bs3scfmcwy95vas0)
+![](/img/assets/cli-linux-01.png)
 
 Download the Binaries for the Masq software:
 
 [Open link](https://github.com/MASQ-Project/Node/actions)
 
 Binaries are different versions of the software that change each time a new feature or fix is added. The simplest way to get started it to pick a set of Binaries which show a green tick like this
 
-![](/img/assets/afvh3dn3sslqbmrmpmcl6uirymmrkintahb0pwohiaimpei3era-alpa0-x4qautzhch6gl8bashnxfypk2hatzo_8qv4bc5jd-7utknzdenc-7qz48yfvvsnenpzx4fz7peujos0)
+![](/img/assets/cli-linux-02.png)
 
 :::tip
 
@@ -53,29 +53,29 @@ Click on the Ubuntu version and the download will begin.
 
 Go to downloads and copy and paste the downloaded zip file into your previously created Masq folder. You should now have this<br />
 
-![](/img/assets/eglau51am-bbx-qxrr6wkhy_xbfvf7xjmdzio3cqcclhurp_l99xyrss4zihr6bsyvm0rvmmztbtrtyrxmsjfxtnpswcbriip4xisq1ac-5vnajjahc7ull8_fnmnljzohz6f4wns0)
+![](/img/assets/cli-linux-03.png)
 
 1. Right click the file and select extract here and you will get a folder named Build results ubuntu-latest go in the folder then generated and then bin and you will see this
 
-![](/img/assets/30a9hnug9svpvgbh0hdmdu_plpmnferjrxuzyuhqa_p8bvuqft61bocyvaaanzf87sxebsmec3hyhl5asqsoyzodd_vo6bascv4ys3lbskzqvhoyshqp7-swutjelwd9s5t8f1zus0)
+![](/img/assets/cli-linux-04.png)
 
 These are the files you want for testing. Copy them and paste into your Masq folder.
 
 You should see something like this
 
-![](/img/assets/1yc-dnyfrnn_edl0psba3qrrul_ypzgujvqrn2jaen8vknw9biycjkwsqpoug3lwxj5hdwczpd-ih0n9qzda9hqyr73eldwar2znhvtlsgjxaj1l95baody3sddn7givuxfxvoi7s0)
+![](/img/assets/cli-linux-05.png)
 
 Now we have the Binaries and we are ready to start using terminal
 
 ## Start the Commandline Interface (CLI)
 
 Now right click anywhere in the folder to open the drop down box in there choose Open in terminal or alternatively you can press Ctrl + Alt + T to open the terminal.
 
-![](/img/assets/iy70ju6r3jl0rjqxdjtmudpuhhbrkmenlfz8hfkii1iobm2bczztozy_10pd49fi7nn9p38lxuwofwpvv1i9zd2rfcauk-harh9akvdgijouxhe36qajt9t3vmyfqibug3rnjc6xs0)
+![](/img/assets/cli-linux-06.png)
 
 We are now in the terminal, it should show that we are in the masq folder, if you are not in the masq folder type cd Masq and it should bring you right into the Masq folder
 
-![](/img/assets/rq8m7-saozv9wa9pylyjmhebgrmgt00rgxnoaakhrafpulizsm3v303oa51c_mzc1jidg2ehyvypeban0jsgqa5aujwapkf7rpcxuzrc2e40t7jwbqbceggy6gv-yk-zmkhfxfh6s0)
+![](/img/assets/cli-linux-07.png)
 
 ### Give Execute Permissions to MASQ Binaries
 
@@ -91,7 +91,7 @@ Now it's time to start the MASQ Daemon (`MASQNode`):
 
 You should see this:
 
-![](/img/assets/5m0v6uwks0jtrebqgm2dzybcqqbadhxwdlgdtt4qaeewxwv4mqmevz8sy_o27spvq7b9hcwo_l8gboskejscodqcl4pfcwud2eewcxvy67pkgrhookk0lnlolai3asxya5ft1woes0)
+![](/img/assets/cli-linux-08.png)
 
 Now open another terminal window **(do not close the daemon window)** in the same manner as before - here we will now start the `masq` interactive tool
 
@@ -100,13 +100,13 @@ Now open another terminal window **(do not close the daemon window)** in the sam
 
 We are now in **interactive mode** which shows a blinking curser after `masq>` and this makes your life easier (you can stay in standard mode but that requires a few more commands and you will get to know this as you test)
 
-![](/img/assets/h5usmq1s7r_5kcy3ht-ryjehv7rwyjgbiw7cf3esedtnwqbhqewgdq3e8hpsmx2off3zw3ot6n6lspxzosni_amchbvmejx9wnkiyffimr5ef-m4ob1mbm4os8p_rojw8z-qvwh2s0)
+![](/img/assets/cli-linux-09.png)
 
 Now type: `setup` and press enter
 
 You are now in the setup mode where you can configure the nodes many settings
 
-![](/img/assets/bjf6nyhdkujxtmlcazwebyhox5zwwqqyadmg_9quixmiqkbr78qmwjo-64ealivfrxponupe3j7zwsi2crnmrhmexkw2uuhitxvtfryklbqn_grwwnm1eihxph1rqs2n5eqtfxdjs0)
+![](/img/assets/cli-linux-10.png)
 
 A breakdown of what these are and how you configure them can be found [here](https://github.com/MASQ-Project/Node/blob/master/README.md#run-masq-node-locally)
 
@@ -130,13 +130,12 @@ In order to specify a ip type `setup --ip 1.2.3.4`and press enter
 
 You should see this:
 
-![](/img/assets/t65etw3c3ski5jiiiuhs_5rc5txrdcbqra3pbhnkmoln6bbwbvrusll9xnvbdwk1e350ur_tmmsao42nr2chask_naifpmobkz556got4wne-xzdwcfpgn4wrnvd0wf2hyknxcms0)
+![](/img/assets/cli-linux-11.png)
 
 \
 This shows us the setup list again but now the **STATUS** alongside ip is `Set` to 1.2.3.4 and the `ERRORS` message has disappeared.‌
 
-## Starting `masq` Node Process <a href="#starting-masq-node-process" id="starting-masq-node-process"></a>
-
+## Starting `masq` Node Process \{#starting-masq-node-process}
 We can now start the Node by typing… Wait for it. `start`
 
 :::info
@@ -147,7 +146,7 @@ We can now start the Node by typing… Wait for it. `start`
 
 If you have followed the guide correctly you should see something like this in the terminal window
 
-![](/img/assets/xewbs2poztzzyas8h-vlbosh-xjaherhkifipcrrop_hjzigom51kt8b1av2w-zxzslbapt1qiovhutiwj8rbhz7ytfqtvk9ldeepteuapgby16enmgvhb9hk-ac6tfmu8imih4ts0)
+![](/img/assets/cli-linux-12.png)
 
 You should also see some action on the Daemon CLI screen which we opened, started and then left alone.&#x20;
 

diff --git a/docs/advanced-use/cli-startup-guides/masq-cli-windows.mdx b/docs/advanced-use/cli-startup-guides/masq-cli-windows.mdx
@@ -27,13 +27,13 @@ If you have previously tested MASQ Node you need to DELETE ALL OLD NODE DATABASE
 
 Create a new folder called Masq on your C drive:\
 \
-![](/img/assets/hoy358oqj1fecvunwa9nj8oomw9sa4uoufwvtlou29tdkqvkwvpsilqo165slfcvgui4zntubgnghkkli4oqtsppxy-i748c9ycqp4zt71hs4nfnavrvjvrpsdbyhm7_n_yvyxqs0)\
+![](/img/assets/cli-windows-01.png)
 Navigate to your `C:` drive
 
 Right click the mouse, Scroll down to New then Folder and click it.\
 Rename that folder `Masq`&#x20;
 
-![](/img/assets/_dq6nnchantnjzbyvey1jyjznowx8ouxjodeazo1zxt-4eax5uuyl-ssdbpcyf7mhetrsg-4lfml4l0eq41dfgmvb_28-j3sklpm3a7yjt9jnaje4dhijasu25udajc6gwagdvbzs0)
+![](/img/assets/cli-windows-02.png)
 
 Download the latest Binaries for the **MASQ Node** software here:<br />
 
@@ -49,15 +49,15 @@ Go to downloads and cut/paste the downloaded zip file into your recently created
 
 You should now have this:
 
-![](/img/assets/c9dc4jd1oyoazgye5i-ariqidbasylcw878tdx6kesro2qfoufrzumdk1wq_kprj2xo81eu01ftamgvkgpw9wczp6ft36nfcic5voh7gy9ihcityjzjhtrqrizyda5hyf9h4dwmqs0)
+![](/img/assets/cli-windows-03.png)
 
 Right click the file, select **Extract here** and you will get the below:
 
-![](/img/assets/t6-vzvxshxfsrcviqtoazeiywbcak6ejr5p9gpmgqa9yowyqjrslyhfjjldzf1bwdbz9hwntir4de2vfwbhkkjynvbabbqvbw7kjppidw3mq9pbupjpmgrjjlwpwjsxbxhohv2svs0)
+![](/img/assets/cli-windows-04.png)
 
 These are the files you want for testing. Copy and paste into your `Masq` folder. You should see something like this:
 
-![](/img/assets/rs4kq4aj2tdzrvmz9noikj1vu5mgjdbept5aeohbpebrtt_twjlwl496jpzlu5aqz1fzdqmunc78gvs4_qabkjze7hm_esbp9fmsttsywv0b4oujug1v0owojg8qubkhl1gk7j2os0)
+![](/img/assets/cli-windows-05.png)
 
 Now we have the Binaries (MASQNode and masq) and we are ready to start using CLI.
 
@@ -67,11 +67,11 @@ To run MASQ Node from CLI you will need to use a command line console or termina
 
 Using the Windows search bar type:   `command`
 
-![](/img/assets/rsdc88frsiq6-2uudntismet8pnxkfjqkbvrtvwm-o62w4lt_-u8ds72yygsmpuu8qkh4ptiik28spsogfetwy7z-_h7couy_0tqsguxant4hjz6a-__meuijet85hkjxqw4xnm9s0)
+![](/img/assets/cli-windows-06.png)
 
 On the right hand side, click 'Run as Administrator' and click **Yes** on the confirmation message that pops up. You should see this:
 
-![](/img/assets/yobbopggqoqjkcdi19n_hu3riqidecsmes5djjucwhryitstuqlfmzw0vaply4mw6gvmgojnqrvb_u0dxocppt0w4g7u-_bqficoxqnqbd408wmepmkv1j2ppw-wq9tpa3e1y5kfs0)
+![](/img/assets/cli-windows-07.png)
 
 We now have to navigate to the Masq folder you created earlier using this CLI. These commands assume you have created the Masq folder in the same location as I did above. Creating that folder elsewhere will mean the below command may not work and you will have to navigate to the Masq folder in the location you created it.
 
@@ -82,7 +82,7 @@ We now have to navigate to the Masq folder you created earlier using this CLI. T
 
 CLI should now show you are in the right place:
 
-![](/img/assets/apr4nzkz9thibgmbp9d6jkyg42wizjne1damsopw-cunp_czhyt9h1bpa49v7dfogkj5pznbi-fn6wksdorcja9ojtnpv9ilwj9r-glybn-xr0clo752ui977jb6qpaqjssiaa5_s0)
+![](/img/assets/cli-windows-08.png)
 
 ## Initialize the Daemon (MASQNode binary)
 
@@ -102,13 +102,13 @@ You may get a pop up window where your Antivirus scans the file, wait for that t
 
 :::
 
-![](/img/assets/rdjjifh4wmlmhbds00dbpecbdrcgzhz5vgd8tj-xjxavhtdqm9ppojmzuay1xk9dvod9j78vapmphywx41vukkore5p0pjceuibfz-4rssmmrtovvaxdhvqa_uf_gbhakpa79rbs0)
+![](/img/assets/cli-windows-09.png)
 
 We now need to open another CLI window as we did before, but this time do not type anything yet.
 
 You should now have 2 CLI open that look like this:
 
-![](/img/assets/ggprep8s1zxeyruonwtmolbk62jcrsrytj8trabcgm27pinzo4fzcz6glnacer9gmux-tystbn6jms8fr2tvs0ajh7dj9fjhab7y7aohqxjz7lmd7lgndtwrd9bsf07nwdgdr_f5s0)
+![](/img/assets/cli-windows-10.png)
 
 :::info
 
@@ -125,7 +125,7 @@ Press **Enter**
 
 We are now in interactive mode which makes your life easier (you can stay in standard mode but that requires a few more commands and you will get to know this as you test).
 
-![](/img/assets/vbzmm_p6uvtkj92x7wr_hrpv6cl9giarl-jxce8urbyjcsx8qnth-nzpikbvtvwiq5ixjf_kqfthhj9shtwgurqfgbvrmpzbqsdb_8rdmxpwljkytbtehazlxhn1q8maiglx5n00s0)
+![](/img/assets/cli-windows-11.png)
 
 ## Setting Configuration for MASQ Node
 
@@ -134,7 +134,7 @@ Type: `setup`
 Press **Enter**\
 You should see the below:
 
-![](/img/assets/7prnoz85unjamr7ep0ga3ds2lrxhazlpiyw90zvpa1zwrzdizax2nrw0oiwq21wqvguge0znsi57kuztekueutyk9am2-_edacflmbicnuglkfoeiqxhnkaossnosx1lzuox5w9us0)
+![](/img/assets/cli-windows-12.png)
 
 A breakdown of what these are and how you configure them can be found below:
 
@@ -158,7 +158,7 @@ Press **Enter**
 
 You should see this:
 
-![](/img/assets/zgkrw8pm7d4prbdo87utbolynodw5v4svft-lcwzij3_d49slw8tmegucdzckyta0skcenemyfgrrjfsmp74d-3_p4t1fep_9kwr6tragbflrhbwblm7s0wgu_dcyvyistbzmsuys0)
+![](/img/assets/cli-windows-13.png)
 
 This shows us the setup list again but now the **STATUS** alongside ip is `Set` to 1.2.3.4 and the `ERRORS` message has disappeared.
 
@@ -175,7 +175,7 @@ In Windows, you may see an admin prompt asking you to allow 'masqnode' process t
 Press **Enter**\
 If you have followed all the above correctly you should see something like this:
 
-![](/img/assets/y2oclfwbrokwxnmczsdhgz6mdlpojrtimpwewmiggi-b4vsmrxkg6roqvwhzd3jrecyl1srcq9bozwhuxq_4hun_0fwqitqncvuymmywqrultq-egaopkmasdfjurflbvkknism-s0)
+![](/img/assets/cli-windows-14.png)
 
 You should also see some action on the Daemon CLI screen which we opened, started and then left alone.&#x20;
 

diff --git a/docs/advanced-use/common-challenges/index.mdx b/docs/advanced-use/common-challenges/index.mdx
@@ -1 +1,7 @@
+import DocCardList from '@theme/DocCardList';
+
 # Common Challenges
+
+Troubleshooting tips for issues that often block MASQ Node from starting or connecting — firewall rules, Port 53 conflicts, and Linux `--real-user` permissions.
+
+<DocCardList />
diff --git a/...nced-use/common-challenges/untitled-3.mdx → ...se/common-challenges/port-53-problems.mdx b/...nced-use/common-challenges/untitled-3.mdx → ...se/common-challenges/port-53-problems.mdx
@@ -1,7 +1,6 @@
 # Port 53 Problems? (usually in Windows)
 
-## Identification <a href="#identification" id="identification"></a>
-
+## Identification \{#identification}
 When you try to start your MASQ Node, do you see a message that looks something like one of these?
 ```
 thread 'main' panicked at 'Cannot bind socket to V4(0.0.0.0:53): Os { code: 10048, kind: AddrInUse, message: "Only one usage of each socket address (protocol/network address/port) is normally permitted." }'
@@ -16,34 +15,27 @@ If you see both of those parts in the message, then you are definitely afflicted
 
 If you don't care about what the problem is or why it happens, and you just want to know how to fix it, skip down to the **Solutions** section.
 
-## Background <a href="#background" id="background"></a>
-
-### Windows <a href="#windows" id="windows"></a>
-
+## Background \{#background}
+### Windows \{#windows}
 Windows includes a service called Internet Connection Sharing (ICS) that listens on port 53. It's a somewhat dated service from the days before widespread WiFi availability that allows you to make your Windows machine a nexus through which other people can connect their machines to the Internet. If you're not already aware that you're doing this, you probably don't need to have ICS active.
 
-### Linux <a href="#linux" id="linux"></a>
-
+### Linux \{#linux}
 Some Linux distributions (we know about Ubuntu Desktop >=16.04 and some versions of Mint, but there are probably others) come with an installed utility called `dnsmasq`. This utility is intended to let folks with small home LANs give intelligible names to their computers, printers, TVs, DVRs, mobile devices, and other Internet-enabled devices, rather than having to reference them by numeric IP address. You may instead have a distribution (for example Ubuntu 18.04) that uses `systemd-resolved` for this purpose. We'll generically call this dns caching.
 
 DNS caching works by putting up a small DNS server on your local machine that fields name-resolution requests for things like "LivingRoomTV" and returns IP addresses like 192.168.0.47. This means that when you want to control your TV from upstairs, or watch its video feed, or whatever it allows you to do remotely, you can call it "LivingRoomTV" (or select it from a list) rather than having to remember its IP address (which may change unexpectedly).
 
-### In General <a href="#in-general" id="in-general"></a>
-
+### In General \{#in-general}
 Any software that uses a DNS server to convert an intelligible name into an IP address will contact that DNS server on Port 53; it's part of the widely-accepted DNS protocol. Therefore, every DNS server must listen on Port 53 for requests if it expects to receive any.
 
 Unfortunately, only one server can listen on Port 53 (or any port) at one time.
 
-## The Problem <a href="#the-problem" id="the-problem"></a>
-
+## The Problem \{#the-problem}
 MASQ Node also includes a small DNS server that allows applications on your computer to send and receive data on the MASQ Network. Since this is a DNS server, it must also listen on Port 53. This means that a DNS-subverting MASQ Node and preexisting port 53 software are irredeemably inimical to one another and cannot ever operate simultaneously on the same computer.
 
 Eventually, MASQ Node will be able to operate in regimes other than DNS subversion, which means that under some circumstances, and in the presence of certain sacrifices, it will be compatible with other port 53 software; but that's in the future, not the present.
 
-## Solutions <a href="#solutions" id="solutions"></a>
-
-### Windows <a href="#windows-1" id="windows-1"></a>
-
+## Solutions \{#solutions}
+### Windows \{#windows-1}
 Internet Connection Sharing can be an annoyance. We had problems with it starting spontaneously after we stopped it, and reenabling itself and starting after we disabled it, and coming back into action over a reboot, in all cases monopolizing port 53 and preventing MASQ Node from starting. However, the solution turned out to be simple: we just installed all pending updates (in our case, they ended at version 1809), and the problem went away. We disabled ICS, and it stayed disabled.
 
 ICS can be enabled and disabled for individual network interfaces, but you'll need to disable it across your entire system to free up port 53 for MASQ Node.
@@ -52,16 +44,13 @@ To do so, press your Windows button and type Services. Scroll down to where you
 
 If it is, then right-click on the Internet Connection Sharing item and choose Properties. Pull down the "Startup type" list and choose "Disabled" so that it can't be restarted once it stops. Now click the "Stop" button to kill the service. You'll get a dialog box with a progress bar; the service should stop fairly quickly. After it does, click "OK" and verify that the service list now shows the service as "Disabled" in the "Startup Type" column, with no value at all in the "Status" column. If that's the case, you've successfully disabled ICS.
 
-### Linux <a href="#linux-1" id="linux-1"></a>
-
+### Linux \{#linux-1}
 We know of two reasonable solutions to the **Port 53 Problem** in Linux: a complicated and annoying one that allows you to keep using dns caching, and a much simpler and easier one that consists of disabling dns caching but will no longer allow you to use intelligible names for the devices on your LAN.
 
-#### Complicated And Annoying: Docker <a href="#complicated-and-annoying-docker" id="complicated-and-annoying-docker"></a>
-
+#### Complicated And Annoying: Docker \{#complicated-and-annoying-docker}
 This solution is too complex to detail here, but in broad strokes it involves running a Docker container that contains a version of Linux that does _not_ have the **Port 53 Problem**, starting the MASQ Node and a browser in that container, and having the browser display its window on the X11 server running on your host machine. We at MASQ have used this solution in the past, and you can see how we've done it by looking in our [source code](https://github.com/MASQ-Project/Node/tree/master/node/docker/linux_node). After installing Docker on your machine, you may be able to put together a similar solution.
 
-#### Simple But Incompatible: Disable DNS Caching <a href="#simple-but-incompatible-disable-dns-caching" id="simple-but-incompatible-disable-dns-caching"></a>
-
+#### Simple But Incompatible: Disable DNS Caching \{#simple-but-incompatible-disable-dns-caching}
 **Ubuntu 18.04**
 
 Disable the service:

diff --git a/...nced-use/common-challenges/untitled-2.mdx → ...challenges/user-permissions-real-user.mdx b/...nced-use/common-challenges/untitled-2.mdx → ...challenges/user-permissions-real-user.mdx
@@ -1,6 +1,6 @@
-# User permissions --real-user
+# User permissions (`--real-user`)
 
-## User permissions --real-user
+## User permissions `--real-user`
 
 The Node will refuse to run unless it can relinquish root privileges once it has opened its ports. Long-running root-privileged servers with network access are a serious security risk.