Major confusion about .gsd folders, symlinks etc.

[movy]

Hello,
Trying to move my vibe-flow onto gsd-2 and having some serious issues with how .gsd folders/links are set up.

I am solo dev, but would like to keep all milestones, docs, specs etc. inside repo to avoid headache with backups, moving to another machine etc., so early in my gsd journey I realised (and was surprised) that it was not a default for gsd-2. It's a bad architectural decision imho, that will cause lots of pain down the line for devs (users) who suddenly discover that their repo is decoupled from their AI agent's knowledge, memory, accomplished tasks etc. and they have to re-init gsd basically from scratch, but I digress.

After finishing couple of milestones and totally not enjoying lack of visibility into docs and specs (as they live outside of repo now, somewhere like /home/ubuntu/.gsd/projects/82e06bf34cd6) my decision was to switch to mode: team as described here. The docs omit the most important point about how to move existing .gsd data into repo, but I assume (and hope) it's just moving /home/ubuntu/.gsd/projects/82e06bf34cd6 folder into project dir.

This is where second surprise awaits. As I just learned, there're THREE .gsd folders, one is global (/home/ubuntu/.gsd/), another one is project-scoped (/home/ubuntu/project/.gsd/), and another one is subproject one (e.g. /home/ubuntu/project/frontend/.gsd/). To be honest, I wouldn't mind gsd internal data structures, but what really baffled me is when I logged in into GSD web-UI, I was welcomed with list of projects to select (basically, list of folders inside /home/ubuntu/project with /home/ubuntu/project/frontend/ already inited), and empty preferences even though I have already finished /gsd onboarding. What I learned later is that there're at least two PREFERENCES.md files (one global, one for project), but looks like global empty PREFERENCES.md (inside /home/ubuntu/.gsd) takes precedence over project one, so none of my already set up project-scoped preferences were respected (inside `/home/ubuntu/project/.gsd/PREFERENCES.md).

In addition, some milestones were saved to global .gsd folder, some to project... with conflicting numbers. What else is duplicated between these folders? How does gsd pick up which .gsd folder to use for a particular session?

I read most of docs in this repo and on https://getshitdone.help, none of them touch these important details about basic initial setup. I am still not sure whether it makes difference to run gsd from project folder or from home folder or start it via VSCode GSD-2 extension.. do they pick up same settings, specs, memories etc or not? How to make this choice visible?

I really want to make GSD-2 work, as for complex projects this harness seems like the only way to keep moving forward w/o losing one's mind, but these little details turn learning J-curve into a brickwall.. any help is appreciated.

Thank you.

[reikjarloekl]

My thoughts exactly on the decision to have .gsd symlinked into the project folder. I'm mostly solo, too and would still want the project history kept safe in the repo.