WORLD KNOWLEDGE & OPPORTUNITY TREE
COMPLETE BEGINNER'S GUIDE — WINDOWS, VS CODE & PYTHON
======================================================

1. WHAT IS IN THIS PACKAGE?
- generate_world_ideas.py: an OFFLINE Python program that generates conceptual records.
- 195_countries.csv: reference country list (required next to the Python script).
- list.txt: index of 19,500 planned 50-million-record archives.
- sample/: small example ZIP.
- README.txt and this guide.

IMPORTANT: This package does NOT contain 975 billion generated records. It can generate up to 195 x 5 billion indexed conceptual combinations. These are NOT 975 billion independently verified jobs, businesses or inventions. It does not use an API, internet data or AI to discover new jobs. Scenario numbers may vary without representing meaningfully different ideas.

2. DOWNLOAD AND INSTALL VISUAL STUDIO CODE
- Open https://code.visualstudio.com/download
- Choose the Windows installer and follow its installation steps.
- Open Visual Studio Code after installation.

3. DOWNLOAD AND INSTALL PYTHON
- Open https://www.python.org/downloads/windows/
- Download a current stable Python 3 Windows installer.
- If offered, select 'Add python.exe to PATH' during setup, or use the Python install manager instructions.
- Finish installation, then RESTART VS Code so the terminal recognizes Python.

4. EXTRACT THIS ZIP
- Right-click this ZIP in Windows File Explorer > Extract All.
- Example destination: D:\worldideas
- Verify the extracted folder contains generate_world_ideas.py AND 195_countries.csv at the same level.
- Do not run the script from inside a ZIP preview.

5. OPEN THE PROJECT IN VS CODE
- File > Open Folder > select D:\worldideas (or your extracted folder).
- Terminal > New Terminal.
- Select PowerShell if asked.
- The terminal prompt should point to the folder containing the script.
- If necessary: cd 'D:\worldideas'
- Verify files: dir

6. CHECK PYTHON
In PowerShell, type:
    python --version
If 'python' is not found, try:
    py --version
If neither works, reinstall Python and check PATH; restart VS Code.
If 'python' opens the Microsoft Store, check Windows App Execution Aliases or use 'py'.

7. FIRST TEST (10,000 RECORDS)
    python generate_world_ideas.py --country JP --rows 10000
This generates a ZIP under the 'output' folder. Progress prints after each TXT finishes. With the default --per-txt 1000000, a 10,000-row test prints one completion update.
If your Python command is 'py', replace 'python' with 'py' in every example.

8. OPEN THE RESULT
    dir .\output
Open the ZIP using Windows Explorer or 7-Zip; inside is one or more TXT files.
TXT columns are tab-separated (TSV). For large TXT files, use a large-file viewer; Notepad may be slow.

9. GENERATE ONE MILLION RECORDS
    python generate_world_ideas.py --country US --rows 1000000 --per-txt 100000
This creates 10 TXT files inside one ZIP, 100,000 records each.

10. GENERATE A 50-MILLION-RECORD ZIP
    python generate_world_ideas.py --country JP --part 1 --rows 50000000 --per-txt 1000000
This creates 50 TXT files in one ZIP. Expect potentially many hours and significant disk space. Run a small test first.

11. GLOBAL INDEX AND COUNTRY MAPPING
195 countries x 5,000,000,000 indexed entries = 975,000,000,000.
100 ZIPs per country x 50,000,000 entries = 5,000,000,000 per country.
19,500 ZIPs total.
Global ZIP number = ceiling(global record ID / 50,000,000).
For global ID 900750000000, global ZIP number = 18015.
To generate only a SMALL TEST of this part:
    python generate_world_ideas.py --global-part 18015 --rows 10000
To inspect one record instantly without generating a ZIP:
    python generate_world_ideas.py --lookup 900750000000
Note: a partial ZIP created with --rows 10000 is NOT a completed 50-million-record part. The script skips an existing valid ZIP with the same name even if it contains fewer rows. Use a different --output folder for samples versus full runs.

12. OTHER COUNTRIES, WORLDWIDE APPLICATION, AND FUTURE SETTINGS
List countries:
    python generate_world_ideas.py --list-countries
China as reference:
    python generate_world_ideas.py --country CN --rows 10000
Apply to a named region:
    python generate_world_ideas.py --country US --application 'Nairobi, Kenya' --rows 10000
Speculative Mars setting:
    python generate_world_ideas.py --country JP --location Mars --rows 10000
These options describe conceptual combinations. They do not verify a real market or job in the chosen location.

13. MONITOR PROGRESS
The program prints a line after each TXT file is completed, e.g.:
    ZIP 00001: 1,000,000/50,000,000 (2.00%) elapsed 300s
To get more frequent progress updates, use --per-txt 100000 (500 TXT files for 50 million records).
Open a SECOND PowerShell terminal and run:
    Get-Process python -ErrorAction SilentlyContinue
To inspect output file sizes:
    Get-ChildItem .\output -File | Select-Object Name,Length,LastWriteTime
A growing .tmp file is not a completed ZIP. Do not open, rename, or delete it while Python is writing.

14. IMPORTANT: AVOID OVERWRITING PARTIAL TESTS
The output filename is based on the global part and country, not --rows, --application, or --location. Therefore:
- Use --output sample_output for tests.
- Use --output full_output for full 50-million-record runs.
- Use separate output folders for Earth, Mars, or different applications.
Examples:
    python generate_world_ideas.py --country JP --rows 10000 --output sample_output
    python generate_world_ideas.py --country JP --part 1 --rows 50000000 --output full_output
The script will skip an existing valid ZIP of the same filename, regardless of its record count. It does NOT resume midway through a .tmp file.

15. COMMON ERRORS
'python is not recognized': check installation, PATH, restart VS Code; try 'py'.
'No such file: 195_countries.csv': open the extracted folder; keep the CSV next to the .py file.
'PermissionError [WinError 32]': another process may be using the output file. Close Explorer/ZIP viewers and check for a second Python process. Do NOT delete a .tmp file until you have confirmed its owner has stopped and inspected it.
'Existing ZIP is damaged': inspect or back up the file before moving/removing it.
'Temporary file exists': check whether another generator is running; the script cannot automatically resume an interrupted archive.
Disk full: free space or choose another drive via --output.
Slow generation: try 10,000 or 100,000 rows first. Compression, storage speed, and antivirus affect performance.

16. RUNNING A WEBSITE VS RUNNING THIS GENERATOR
This Python program is a command-line generator, NOT a ready-made public website.
You do NOT need PHP, XAMPP, a VPS, or hosting to run it locally.
A future website would need a separate web interface and appropriate server-side integration.

17. SAFETY AND QUALITY NOTES
- Generated entries are conceptual, not verified facts or real job vacancies.
- Country focus labels are illustrative and not comprehensive research.
- Mars and interplanetary entries are speculative.
- Do not treat generated medical, legal, financial or engineering ideas as professional instructions.
- Large-scale generation may require enormous disk space and time.

18. QUICK COMMAND CHEAT SHEET
    python --version
    python generate_world_ideas.py --list-countries
    python generate_world_ideas.py --country JP --rows 10000 --output sample_output
    python generate_world_ideas.py --lookup 900750000000
    python generate_world_ideas.py --country US --rows 1000000 --per-txt 100000 --output sample_output
    python generate_world_ideas.py --country JP --part 1 --rows 50000000 --per-txt 1000000 --output full_output

END OF GUIDE
